# O Klinio, direto do seu código.

Inicie as mesmas buscas do site, consulte seu histórico e receba as empresas em JSON. A API usa os créditos da sua conta, incluindo os créditos diários gratuitos.

- URL base: https://klinio.io/api/v1
- OpenAPI 3.1: https://klinio.io/openapi.json
- Servidor MCP: https://klinio.io/api/mcp (https://klinio.io/pt/developers/mcp)
- Access for AI agents: https://klinio.io/auth.md

## Início rápido

1. Inicie uma busca com o quê e onde (query e location), ou com um link que o Klinio lê: uma busca do Google ou do Google Maps, um diretório do Clutch ou sites de empresas.
2. Acompanhe. A maioria das buscas termina em poucos minutos; as empresas aparecem à medida que são encontradas.
3. Leia as empresas: site, e-mails e telefones.

```bash

curl -X POST https://klinio.io/api/v1/searches \
  -H "Authorization: Bearer $KLINIO_KEY" -H "Content-Type: application/json" \
  -d '{"query": "web design agencies", "location": "Ankara", "limit": 50}'
curl https://klinio.io/api/v1/searches/SEARCH_ID -H "Authorization: Bearer $KLINIO_KEY"
curl "https://klinio.io/api/v1/searches/SEARCH_ID/results?only=contacts" -H "Authorization: Bearer $KLINIO_KEY"

```

## Endpoints

Envie a chave no cabeçalho Authorization como Bearer kl_live_… e os corpos das requisições em JSON. Toda resposta é JSON.

- `POST /searches`: Inicia uma busca. Envie query e location (o quê e onde: uma busca no Google Maps), ou link (um link de busca, ou sites), ou websites (uma lista). Opcionais: limit (de 1 a 500 empresas) e country (duas letras, para um link de busca do google.com).
- `GET /searches`: Seu histórico: todas as buscas iniciadas no site, na extensão ou pela API, da mais recente para a mais antiga. Filtre com source, status, origin, q, since e until.
- `GET /searches/{id}`: Uma busca: o status e quantas empresas encontrou até agora.
- `GET /searches/{id}/results`: As empresas encontradas, 100 por vez (limit até 500). only=contacts mantém as que têm e-mail ou telefone; next_cursor traz a próxima página.
- `DELETE /searches/{id}`: Para uma busca na fila ou em andamento. O que ela encontrou fica.
- `GET /account`: Seu plano e os créditos que restam.

## Seu histórico também está na API.

Toda busca que você inicia no site, na extensão do Chrome ou pela API vai para o mesmo histórico. Liste, filtre e leia as empresas de qualquer busca pelo results_url dela.

- `source`: Onde a busca foi feita. linkedin_list é uma lista do LinkedIn enviada pela extensão, websites uma lista de sites, merged listas que você juntou no site.
- `status`: Em que ponto a busca está. Cada status é explicado mais abaixo.
- `origin`: Onde você a iniciou: no klinio.io, na extensão do Chrome ou pela API.
- `q`: Texto no nome ou nas palavras da busca. Maiúsculas e acentos não importam: cafe também encontra Café.
- `since`, `until`: Pelo momento em que a busca começou: since a partir dele, until até ele. Envie uma data (2026-11-01) ou um horário ISO 8601; uma data em until inclui o dia inteiro.
- `limit`, `cursor`: De 1 a 100 buscas por página (20 se você não indicar). Para a próxima página, envie next_cursor como cursor; total conta todas as buscas que correspondem.

## O status de uma busca

- `queued`: Aguardando a vez.
- `running`: Encontrando empresas e lendo os sites delas.
- `completed`: Pronta. Todas as empresas foram verificadas.
- `stopped`: Parada por você. O que ela encontrou fica.
- `failed`: Não conseguiu terminar. failure diz o porquê.

## Créditos e limites

- Um crédito é uma empresa com e-mail ou telefone, como no site. Empresas sem nada encontrado não custam nada.
- Uma conta gratuita usa os créditos diários; um pacote, o saldo. Sem créditos, uma nova busca responde 402.
- Até 3 buscas na fila ou em andamento ao mesmo tempo por conta, e 120 requisições por minuto por chave.
- Navegadores não conseguem chamar a API: ela não envia cabeçalhos CORS, então a chave fica no seu servidor.

## Erros

Um erro responde com o status HTTP e um corpo JSON: error.code e error.message.

- `unauthorized`: A chave está faltando, errada ou revogada.
- `insufficient_credits`: Sem créditos para uma nova busca.
- `invalid_request`: O corpo ou um parâmetro não é válido.
- `invalid_link`: O Klinio não lê esse link.
- `mixed_input`: Um link de busca e sites na mesma requisição.
- `unsupported_google_tab`: Uma aba do Google que não lista empresas, como Imagens ou Notícias.
- `source_disabled`: Esse site está desativado no momento.
- `too_many_running`: Buscas demais na fila ou em andamento ao mesmo tempo.
- `rate_limited`: Requisições demais neste minuto.
- `not_found`: Nenhuma busca assim nesta conta.
- `not_running`: A busca não está na fila nem em andamento.

- [Preços](https://klinio.io/pt/pricing)
- [API](https://klinio.io/pt/developers)
- [Servidor MCP](https://klinio.io/pt/developers/mcp)
- [Extrator de e-mails do Google Maps](https://klinio.io/pt/google-maps-email-extractor)
- [Buscador de e-mails em sites](https://klinio.io/pt/website-email-finder)
- [Extrator de e-mails do Google](https://klinio.io/pt/google-search-email-extractor)
- [Extrator de e-mails do Clutch](https://klinio.io/pt/clutch-email-extractor)
- [Buscador de empresas do LinkedIn](https://klinio.io/pt/linkedin-company-email-finder)
- [Privacidade da extensão](https://klinio.io/pt/extension-privacy)

---
Page: https://klinio.io/pt/developers
Markdown: https://klinio.io/pt/developers.md
