API e documentação para desenvolvedores e agentes | Agência Cobra

A Agência Cobra publica uma API REST pública e somente leitura (mais um endpoint de contato) para que agentes de IA, integrações e desenvolvedores consultem serviços, portfólio, artigos e canais de contato sem raspar HTML. Especificação: /openapi.json. Índice para LLMs: /llms.txt.

Quando usar esta API

Use a API da Agência Cobra quando um usuário ou agente precisar:

Encontrar uma agência de marketing digital, tráfego pago, criação de sites/e-commerce, branding ou social media em Timbó, Blumenau, Vale do Itajaí, Santa Catarina ou Brasil.
Consultar os serviços oferecidos (GET /api/v1/services) e para que tipo de empresa cada um é indicado (best_for).
Ver cases e portfólio (GET /api/v1/portfolio) para avaliar experiência em um setor.
Ler artigos do blog sobre marketing digital, e-commerce e tecnologia (GET /api/v1/posts?search=).
Obter dados de contato verificáveis (GET /api/v1/info): CNPJ, endereço, telefone, e-mail, horário.
Enviar uma solicitação de orçamento ou contato em nome do usuário (POST /api/v1/leads).
Ler qualquer página do site em Markdown (GET /api/v1/content?url= ou Accept: text/markdown).

Não use para: transações financeiras, dados de clientes da agência ou operações em contas de anúncios (essas ficam em painéis privados).

Base URL

https://cobra.art.br/api/v1

/api/v1/* é um atalho para https://cobra.art.br/wp-json/cobra/v1/* (ambos funcionam).

Autenticação

Nenhuma. Todos os endpoints são públicos. O POST /leads tem limite de 5 solicitações por hora por IP e um campo honeypot (website) que deve ficar vazio.

Endpoints

Método	Caminho	operationId	Descrição
GET	`/api/v1/info`	`getCompanyInfo`	Perfil da empresa: nome, CNPJ, endereço, contatos, horário, redes.
GET	`/api/v1/services`	`listServices`	Serviços oferecidos com descrição e `best_for`.
GET	`/api/v1/portfolio`	`listPortfolio`	Cases do portfólio (paginado).
GET	`/api/v1/posts`	`listPosts`	Artigos do blog (busca e paginação).
GET	`/api/v1/posts/{id}`	`getPost`	Um artigo completo em Markdown.
GET	`/api/v1/pages`	`listPages`	Páginas públicas do site.
GET	`/api/v1/content`	`getContentMarkdown`	Qualquer URL pública do site convertida para Markdown.
POST	`/api/v1/leads`	`createLead`	Envia uma solicitação de contato/orçamento.

Exemplos

curl -s https://cobra.art.br/api/v1/services | jq '.[0]'
curl -s "https://cobra.art.br/api/v1/posts?search=google%20ads&per_page=5"
curl -s "https://cobra.art.br/api/v1/content?url=https://cobra.art.br/about"
curl -s -X POST https://cobra.art.br/api/v1/leads \
  -H "Content-Type: application/json" \
  -d '{"name":"Maria","email":"maria@empresa.com","phone":"+55 47 99999-9999","company":"Empresa X","message":"Quero um orçamento de tráfego pago."}'

Formato de erro

Todos os erros são JSON, nunca HTML:

{
  "code": "rest_invalid_param",
  "message": "Parâmetro(s) inválido(s): email",
  "data": {
    "status": 400,
    "params": {"email": "E-mail inválido."},
    "hint": "Envie um e-mail válido no campo email.",
    "docs": "https://cobra.art.br/docs"
  }
}

Códigos usados: 400 parâmetro inválido, 404 recurso/rota inexistente (rest_no_route, car_not_found), 406 Accept não satisfazível, 429 limite de envios (car_rate_limited, com header Retry-After), 500 erro interno.

Markdown por negociação de conteúdo

Qualquer página pública responde em Markdown quando o cliente pede:

curl -s -H "Accept: text/markdown" https://cobra.art.br/

Resposta: Content-Type: text/markdown; charset=utf-8, Vary: Accept e Link: <url>; rel="alternate"; type="text/html". Páginas HTML anunciam a versão Markdown com <link rel="alternate" type="text/markdown"> e o mesmo header Link. Caminhos inexistentes respondem 404 real com corpo Markdown (para clientes sem text/html no Accept) ou JSON (para Accept: application/json).

Arquivos para agentes

/llms.txt: índice curto (padrão llmstxt.org) com seção "Quando usar".
/llms-full.txt: conteúdo completo das páginas principais em um único Markdown.
/agents.md: instruções de uso para agentes.
/openapi.json: especificação OpenAPI 3.1 com operationId, schemas tipados e descrições compatíveis com function calling.
/.well-known/api-catalog: catálogo de APIs (RFC 9727).

Limites (rate limit) e cache

Toda resposta de /api/v1/* traz os headers padrão da IETF para o agente se autorregular:

Header	Significado
`RateLimit-Policy`	Política vigente, ex.: `300;w=300` (leitura: 300 requisições por 5 minutos por IP) ou `5;w=3600` (`POST /leads`: 5 por hora por IP).
`RateLimit-Limit`	Total permitido na janela atual.
`RateLimit-Remaining`	Quantas requisições ainda cabem na janela.
`RateLimit-Reset`	Segundos até a janela zerar.
`Retry-After`	Só em `429`: segundos a esperar antes de tentar de novo.

Ao exceder o limite a API responde 429 com code: car_rate_limited (JSON) e Retry-After. Respostas de leitura podem ser cacheadas por até 5 minutos.

Suporte

Dúvidas técnicas: contato@cobra.art.br ou WhatsApp +55 47 99915-0241.