# API do Pico

> Pesquisa de nicho (vídeos que viralizaram, ganchos, criadores, tendências), criação de peças com IA, calendário, publicação e leads do Instagram/TikTok de uma PME brasileira — por REST (`/api/v1`) e por MCP (`/api/mcp`). Autenticação: `Authorization: Bearer pico_sk_…`, chave criada em Conta → API e MCP.

Regras que um agente precisa obedecer:
- Rotas que cobram da conta da pessoa exigem `"confirmarGasto": true` LITERAL — só mande depois de a pessoa dizer sim. Sem ele a rota responde 409 com a estimativa e não cobra.
- Publicar e responder exigem `"confirmar": true` LITERAL e o escopo `publicacao` — irreversível na rede; pergunte antes.
- IA (criar peça, análise, tradução) é paga pelo Pico: `custo.fonte: "ia-do-pico"`.
- Erros são `application/problem+json` com `code` estável (lista em /docs/erros).
- Limites por minuto: leitura 120, escrita 30, gasto 6, publicacao 6; 429 traz Retry-After.
- A pesquisa avança quando você consulta GET /api/v1/pesquisas/{id} (poll sob demanda; não há cron).

## Docs

- [Começar](https://app.usepico.digital/docs)
- [Início rápido](https://app.usepico.digital/docs/inicio-rapido)
- [Autenticação e escopos](https://app.usepico.digital/docs/autenticacao)
- [MCP no Claude Code](https://app.usepico.digital/docs/mcp)
- [Gasto e teto](https://app.usepico.digital/docs/gasto)
- [Pesquisa de nicho](https://app.usepico.digital/docs/pesquisa)
- [Peças, agenda e publicação](https://app.usepico.digital/docs/publicar)
- [Erros](https://app.usepico.digital/docs/erros)
- [Limites e paginação](https://app.usepico.digital/docs/limites)
- [Changelog](https://app.usepico.digital/docs/changelog)
- [Políticas](https://app.usepico.digital/docs/politicas)
- [Referência interativa (OpenAPI 3.1)](https://app.usepico.digital/docs/api)
- [openapi.json](https://app.usepico.digital/openapi.json)
- [Todos os guias num arquivo](https://app.usepico.digital/llms-full.txt)

## Rotas

- GET /api/v1/saude — Está no ar? (escopo nenhum; grátis)
- GET /api/v1/openapi.json — A spec OpenAPI 3.1 (gerada na hora) (escopo nenhum; grátis)
- GET /api/v1/eu — Quem é esta chave (escopo leitura; grátis)
- GET /api/v1/chaves — Listar chaves do workspace (escopo sessao; grátis)
- POST /api/v1/chaves — Criar chave (escopo sessao; grátis)
- DELETE /api/v1/chaves/{id} — Revogar chave (escopo sessao; grátis)
- GET /api/v1/perfil — Ler o perfil do negócio (escopo leitura; grátis)
- PUT /api/v1/perfil — Salvar o perfil do negócio (escopo escrita; grátis)
- GET /api/v1/custo — Extrato do mês e teto (escopo leitura; grátis)
- PUT /api/v1/custo/teto — Ajustar o teto de gasto do mês (escopo escrita; grátis)
- GET /api/v1/conexoes — Redes conectadas e o que cada uma permite (escopo leitura; grátis)
- POST /api/v1/conexoes/{rede} — Começar a conexão de uma rede (escopo escrita; grátis)
- GET /api/v1/clientes — Workspaces que o operador vê (escopo leitura; grátis)
- GET /api/v1/hoje — A fila do dia (escopo leitura; grátis)
- GET /api/v1/semana — Os posts desta semana da própria conta (escopo leitura; grátis)
- POST /api/v1/semana — Montar a semana agora (escopo gasto; IA do Pico)
- GET /api/v1/conta — A própria conta de relance (escopo leitura; grátis)
- GET /api/v1/funcionou — A dica funcionou? (escopo leitura; grátis)
- GET /api/v1/pesquisas — Listar pesquisas (escopo leitura; grátis)
- POST /api/v1/pesquisas — Pesquisar um nicho (escopo gasto; US$ 0,50 + US$ 1,00 com inteligência; exige "confirmarGasto": true)
- GET /api/v1/pesquisas/taxonomias — Tipos de gancho, categorias e regiões (escopo leitura; grátis)
- POST /api/v1/pesquisas/sugerir-keywords — Sugerir palavras-chave a partir do intent (escopo leitura; grátis (reasoning traduzido pela IA do Pico))
- POST /api/v1/pesquisas/melhorar-intent — Reescrever uma descrição crua como frase de pesquisa (escopo gasto; IA do Pico)
- GET /api/v1/pesquisas/{id} — Estado de uma pesquisa (e avança se estiver rodando) (escopo leitura; grátis)
- GET /api/v1/pesquisas/{id}/{recurso} — Um recorte do resultado (escopo leitura; grátis)
- POST /api/v1/pesquisas/{id}/traduzir — Traduzir a narrativa da fonte para português (escopo escrita; IA do Pico)
- POST /api/v1/pesquisas/{id}/analise — Relatório por IA sobre o corpus (escopo gasto; IA do Pico)
- GET /api/v1/criadores — Satélites e monitorados (escopo leitura; grátis)
- POST /api/v1/criadores/satelite — Consultar um perfil (satélite) (escopo gasto; US$ 0,50; exige "confirmarGasto": true)
- GET /api/v1/criadores/satelite/{id} — Um satélite (e avança se estiver processando) (escopo leitura; grátis)
- POST /api/v1/criadores/monitorar — Monitorar um criador com cadência (escopo gasto; US$ 0,25 por ciclo; exige "confirmarGasto": true)
- POST /api/v1/criadores/{id}/analise — Briefing por IA de um criador (escopo gasto; IA do Pico)
- GET /api/v1/nichos — Ramos lidos pela esteira (escopo leitura; grátis)
- GET /api/v1/nichos/{id} — Um ramo com os jeitos de fazer (escopo leitura; grátis)
- POST /api/v1/nichos — Pedir a leitura de um ramo inteiro (escopo gasto; ~US$ 10 por ramo; exige "confirmarGasto": true)
- GET /api/v1/instagram/{handle} — Uma conta pública do Instagram (leitura guardada) (escopo leitura; grátis)
- POST /api/v1/instagram/{handle}/ler — Ler agora uma conta pública do Instagram (escopo gasto; US$ 0,003; exige "confirmarGasto": true)
- GET /api/v1/carrosseis — Carrosséis que viralizaram nas contas do nicho (escopo leitura; grátis)
- GET /api/v1/pecas — Listar peças (escopo leitura; grátis)
- POST /api/v1/pecas — Criar uma peça com IA (escopo gasto; IA do Pico)
- GET /api/v1/pecas/{id} — Uma peça (escopo leitura; grátis)
- PUT /api/v1/pecas/{id} — Editar um rascunho (escopo escrita; grátis)
- DELETE /api/v1/pecas/{id} — Apagar rascunho ou cancelar compromisso (escopo escrita; grátis)
- POST /api/v1/pecas/{id}/agendar — Agendar um rascunho (escopo escrita; grátis)
- POST /api/v1/pecas/{id}/publicar — Publicar agora (escopo publicacao; grátis (1 publicação da cota da rede); exige "confirmar": true)
- GET /api/v1/leads — Listar leads (escopo leitura; grátis)
- POST /api/v1/leads/{id}/responder — Responder um lead (escopo publicacao; 1 interação da cota da rede; exige "confirmar": true)
- GET /api/v1/inbox — Inbox da ponte (escopo leitura; grátis)
- GET /api/v1/resultado — Resultado das publicadas (escopo leitura; grátis)

Versão do contrato: 2026-09-11.