Início rápido

Do zero a uma peça agendada, com curl. Todos os exemplos usam a variável PICO_API_KEY:

export PICO_API_KEY="pico_sk_SUA_CHAVE"
export PICO="https://app.usepico.digital/api/v1"

1. Quem sou eu

curl -s $PICO/eu -H "Authorization: Bearer $PICO_API_KEY"

{
  "tenant": { "id": "…", "nome": "Loja da Ana", "modo": "direto" },
  "operador": { "id": "…", "nome": "Ana", "email": "ana@…" },
  "via": "chave",
  "escopos": ["leitura", "escrita", "gasto"],
  "limites": { "leitura": { "janelaS": 60, "max": 120 }, "gasto": { "janelaS": 60, "max": 6 } },
  "versao": "2026-09-11"
}

Se vier 401, a chave está errada, revogada ou expirada — crie outra em Conta → API e MCP.

2. Conte sobre o negócio (uma vez)

O perfil alimenta a pesquisa, o contexto da IA e o texto do direct. É o mesmo formulário da tela:

curl -s -X PUT $PICO/perfil -H "Authorization: Bearer $PICO_API_KEY" -H "content-type: application/json" -d '{
  "nome": "Loja da Ana",
  "segmento": "loja de roupa feminina",
  "descricao": "roupa casual para mulheres de 25 a 40, loja física em SP e site",
  "publico": "mulheres de 25 a 40 que compram online",
  "objetivo": "venda",
  "regiao": "São Paulo",
  "idioma": "pt"
}'

GET $PICO/perfil mostra o que está gravado e completo: true quando o mínimo está lá.

3. Pesquise o nicho (gasta)

Primeiro veja o que custa — sem confirmarGasto a rota não cobra:

curl -s -X POST $PICO/pesquisas -H "Authorization: Bearer $PICO_API_KEY" -H "content-type: application/json" -d '{
  "intent": "conteúdo de moda casual para mulheres de 25 a 40 em São Paulo, para vender roupa online",
  "keywords": ["look do dia", "moda casual", "dicas de estilo"],
  "platforms": ["instagram", "tiktok"],
  "dataIntelligence": true
}'

{ "status": 409, "code": "gasto_nao_confirmado", "detail": "Pesquisar este nicho custa cerca de US$ 1,50. Repita com \"confirmarGasto\": true para seguir.", "estimativaUsd": 1.5 }

Agora com a confirmação (e um Idempotency-Key, para uma rede que caiu não virar dois débitos):

curl -s -X POST $PICO/pesquisas -H "Authorization: Bearer $PICO_API_KEY" -H "content-type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" -d '{ "...igual acima...", "confirmarGasto": true }'

Resposta 202 com o cartão da pesquisa (status: "running"), o custo real cobrado e o próximo passo.

4. Espere terminar

A pesquisa avança quando você pergunta — não há cron. A cada ~5 s:

curl -s $PICO/pesquisas/ID -H "Authorization: Bearer $PICO_API_KEY"

Quando vier "status": "completed", contagens diz quantos vídeos, ganchos e tendências chegaram. Leva de 2 a 6 minutos.

5. Leia o resultado — em português

curl -s -X POST $PICO/pesquisas/ID/traduzir -H "Authorization: Bearer $PICO_API_KEY"   # traduz a narrativa (IA do Pico)
curl -s "$PICO/pesquisas/ID/ganchos" -H "Authorization: Bearer $PICO_API_KEY"          # os ganchos ranqueados
curl -s "$PICO/pesquisas/ID/analise" -H "Authorization: Bearer $PICO_API_KEY"          # a análise
curl -s "$PICO/pesquisas/ID/videos"  -H "Authorization: Bearer $PICO_API_KEY"          # os vídeos por Virality Score

Recortes: videos, criadores, ganchos, sons, hashtags, anuncios, analise, benchmarks, tendencias, resumo. ?idioma=en devolve o bruto.

6. Crie uma peça (IA do Pico, sem custo para você)

curl -s -X POST $PICO/pecas -H "Authorization: Bearer $PICO_API_KEY" -H "content-type: application/json" -d '{
  "kind": "carousel",
  "brief": "Gancho: 3 looks com a mesma calça jeans. Oferta: frete grátis acima de R$ 199.",
  "provenance": { "hookText": "3 looks com a mesma calça", "nicheLabel": "moda casual" }
}'

Volta um rascunho (origem: "rascunho") com o body — no carrossel, um JSON de lâminas {"slides":[{"titulo":"…","texto":"…"}]}. kind aceita script, brief, hooks, carousel.

7. Agende

curl -s -X POST $PICO/pecas/ID_DO_RASCUNHO/agendar -H "Authorization: Bearer $PICO_API_KEY" -H "content-type: application/json" \
  -d '{ "dia": "2026-09-15" }'

201 com postId: a peça virou compromisso no calendário (GET $PICO/pecas?estado=agendada). Publicar de verdade é outra rota, com outro escopo — veja Peças, agenda e publicação.

8. Veja o que precisa de você hoje

curl -s $PICO/hoje  -H "Authorization: Bearer $PICO_API_KEY"   # a fila do dia
curl -s $PICO/leads -H "Authorization: Bearer $PICO_API_KEY"   # comentários e DMs que pedem resposta
curl -s $PICO/custo -H "Authorization: Bearer $PICO_API_KEY"   # o extrato do mês e o teto

A mesma conversa no Claude Code

Com o MCP instalado (como), tudo acima é uma conversa:

"Pesquisa o nicho de moda casual feminina em SP pelo Pico. Antes de gastar, me diz quanto custa."

"Traduz o resultado e me mostra os 10 melhores ganchos."

"Cria um carrossel com o terceiro gancho e agenda para terça."

O Claude usa pico_pesquisa_criar (que responde o custo e espera o seu sim), pico_pesquisa_traduzir, pico_pesquisa_recurso, pico_peca_criar e pico_peca_agendar — os mesmos endpoints, com as mesmas travas.