{ "openapi": "3.1.0", "info": { "title": "API do Pico", "version": "2026-09-11", "description": "A API pública do **Pico** — pesquisa de nicho, criação de peças, calendário, leads e resultado do seu Instagram/TikTok, pelo Claude Code ou por qualquer cliente HTTP.\n\n## Autenticação\n`Authorization: Bearer pico_sk_…`. A chave é criada em **Conta → API e MCP** e aparece uma vez. Rotas de gestão de chave (`/v1/chaves`) aceitam só a sessão do app.\n\n## Escopos\n- `leitura` — Ler perfil, pesquisas, peças, leads, inbox e custo.\n- `escrita` — Salvar perfil, editar rascunhos, agendar peças, ajustar o teto do mês.\n- `gasto` — Pedir pesquisas e gerar peças com IA — gasta dinheiro da sua conta.\n- `publicacao` — Publicar peças e responder leads — age na sua conta do Instagram/TikTok.\n\n## Dinheiro\nRotas que cobram da sua conta exigem `\"confirmarGasto\": true` literal; sem ele respondem **409 `gasto_nao_confirmado`** com a estimativa e não cobram nada. O teto do mês (`PUT /v1/custo/teto`) vale para as chaves. IA (peças, análises, tradução) é paga pelo Pico — `custo.fonte: \"ia-do-pico\"`.\n\n## Agir na sua conta\nPublicar e responder exigem o escopo `publicacao` e `\"confirmar\": true` literal.\n\n## Erros\nRFC 9457 (`application/problem+json`) com um `code` estável. Lista completa em `/docs/erros`.\n\n## Limites\n- `leitura`: 120 chamadas por 60 s\n- `escrita`: 30 chamadas por 60 s\n- `gasto`: 6 chamadas por 60 s\n- `publicacao`: 6 chamadas por 60 s\n\nHeaders `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`; ao estourar, **429** com `Retry-After`.\n\n## MCP\nO mesmo sistema como ferramentas no Claude Code: `/api/mcp` (Streamable HTTP, a mesma chave no header). Guia em `/docs/mcp`.", "contact": { "name": "Pico", "url": "https://app.usepico.digital/docs" } }, "servers": [ { "url": "https://app.usepico.digital", "description": "Produção" } ], "tags": [ { "name": "Sistema", "description": "Saúde e versão." }, { "name": "Conta", "description": "Quem é a chave, perfil do negócio, custo, redes conectadas, fila do dia." }, { "name": "Chaves", "description": "Gestão das chaves — só com a sessão do app." }, { "name": "Ciclo", "description": "O que o Pico vende, para a própria conta da pessoa: os posts desta semana já decididos (com o link da peça para aprovar), a conta de relance e \"a dica funcionou?\". Para um agente, comece aqui." }, { "name": "Pesquisas", "description": "Pesquisa de nicho: vídeos que viralizaram, ganchos, criadores, tendências, análise — em português." }, { "name": "Criadores", "description": "Consulta pontual (satélite) e acompanhamento (monitorar) de perfis." }, { "name": "Ramos", "description": "Ramos lidos inteiros pela esteira (40+ contas): a régua do tamanho e os jeitos de fazer de quem está acima do benchmark." }, { "name": "Carrosséis", "description": "Os carrosséis que viralizaram nas contas do nicho, pela leitura que o Pico já fez das contas: curtidas contra o normal da própria conta." }, { "name": "Instagram", "description": "Uma conta pública do Instagram para agentes: perfil, contatos da bio, posts e quanto cada um rendeu contra o normal da própria conta. Para montar landing page, proposta ou diagnóstico sem raspar o Instagram." }, { "name": "Peças", "description": "Criar com IA, editar, agendar, publicar; resultado das publicadas." }, { "name": "Leads", "description": "Comentários e DMs que pedem resposta; o inbox; responder." } ], "security": [ { "chave": [] } ], "paths": { "/api/v1/saude": { "get": { "operationId": "saude", "tags": [ "Sistema" ], "summary": "Está no ar?", "description": "Sem banco, sem chave, sem segredo. É o que um monitor externo bate.\n\n**Escopo:** `nenhum` · **Custo:** grátis · **Limite:** sem limite", "security": [], "x-escopo": "nenhum", "x-classe": "nenhuma", "x-custo": "grátis", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Saude" } } } } } } }, "/api/v1/openapi.json": { "get": { "operationId": "openapi", "tags": [ "Sistema" ], "summary": "A spec OpenAPI 3.1 (gerada na hora)", "description": "A mesma spec de `/openapi.json`, com a origem da request como primeiro servidor — é o que a referência em /docs/api lê.\n\n**Escopo:** `nenhum` · **Custo:** grátis · **Limite:** sem limite", "security": [], "x-escopo": "nenhum", "x-classe": "nenhuma", "x-custo": "grátis", "responses": { "200": { "description": "A spec (application/json)" } } } }, "/api/v1/eu": { "get": { "operationId": "eu", "tags": [ "Conta" ], "summary": "Quem é esta chave", "description": "A primeira chamada de todo mundo: workspace, operador, por onde entrou, escopos e limites. Não custa nada.\n\n**Escopo:** `leitura` · **Custo:** grátis · **Limite:** 120 por 60 s", "security": [ { "chave": [ "leitura" ] } ], "x-escopo": "leitura", "x-classe": "leitura", "x-custo": "grátis", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Eu" } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } } } } }, "/api/v1/chaves": { "get": { "operationId": "chaves.listar", "tags": [ "Chaves" ], "summary": "Listar chaves do workspace", "description": "Só com a sessão do app (cookie). Chave de API não lista chaves. Nunca devolve a chave inteira — só o prefixo.\n\n**Escopo:** `sessao` · **Custo:** grátis · **Limite:** 120 por 60 s", "security": [ { "sessao": [] } ], "x-escopo": "sessao", "x-classe": "leitura", "x-custo": "grátis", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "itens": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "nome": { "type": "string" }, "prefixo": { "type": "string", "description": "pico_sk_ + 6 caracteres — o que a lista mostra" }, "escopos": { "type": "array", "items": { "type": "string", "enum": [ "leitura", "escrita", "gasto", "publicacao" ] } }, "criadaEm": { "type": "string", "description": "Instante em ISO-8601 UTC, ex. 2026-09-11T12:00:00.000Z" }, "expiraEm": { "anyOf": [ { "type": "string", "description": "Instante em ISO-8601 UTC, ex. 2026-09-11T12:00:00.000Z" }, { "type": "null" } ] }, "ultimoUsoEm": { "anyOf": [ { "type": "string", "description": "Instante em ISO-8601 UTC, ex. 2026-09-11T12:00:00.000Z" }, { "type": "null" } ] }, "revogadaEm": { "anyOf": [ { "type": "string", "description": "Instante em ISO-8601 UTC, ex. 2026-09-11T12:00:00.000Z" }, { "type": "null" } ] } }, "required": [ "id", "nome", "prefixo", "escopos", "criadaEm", "expiraEm", "ultimoUsoEm", "revogadaEm" ], "additionalProperties": false } } }, "required": [ "itens" ], "additionalProperties": false } } } }, "401": { "description": "`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`so_sessao` — A rota é de gestão da própria chave (criar, listar, revogar) e foi chamada com chave de API — chave não cria chave.\n\n`cross_site` — Request com sessão vinda de outro site por script (fetch/XHR). Só o próprio app pode usar a sessão.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "so_sessao": { "$ref": "#/components/examples/so_sessao" }, "cross_site": { "$ref": "#/components/examples/cross_site" } } } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } } } }, "post": { "operationId": "chaves.criar", "tags": [ "Chaves" ], "summary": "Criar chave", "description": "Só com a sessão do app. A chave inteira aparece SÓ nesta resposta. `gasto` e `publicacao` são escopos que gastam dinheiro e agem na sua conta — marque sabendo.\n\n**Escopo:** `sessao` · **Custo:** grátis · **Limite:** 30 por 60 s", "security": [ { "sessao": [] } ], "x-escopo": "sessao", "x-classe": "escrita", "x-custo": "grátis", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CriarChaveEntrada" } } } }, "responses": { "201": { "description": "Criada — guarde `chave` agora", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChaveCriada" } } } }, "400": { "description": "`corpo_invalido` — O JSON não é válido ou não passa na validação do campo (o `detail` diz qual).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "corpo_invalido": { "$ref": "#/components/examples/corpo_invalido" } } } } }, "401": { "description": "`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`so_sessao` — A rota é de gestão da própria chave (criar, listar, revogar) e foi chamada com chave de API — chave não cria chave.\n\n`cross_site` — Request com sessão vinda de outro site por script (fetch/XHR). Só o próprio app pode usar a sessão.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "so_sessao": { "$ref": "#/components/examples/so_sessao" }, "cross_site": { "$ref": "#/components/examples/cross_site" } } } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } } } } }, "/api/v1/chaves/{id}": { "delete": { "operationId": "chaves.revogar", "tags": [ "Chaves" ], "summary": "Revogar chave", "description": "Só com a sessão do app. Irreversível: as ferramentas que usam a chave param na hora.\n\n**Escopo:** `sessao` · **Custo:** grátis · **Limite:** 30 por 60 s", "security": [ { "sessao": [] } ], "x-escopo": "sessao", "x-classe": "escrita", "x-custo": "grátis", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "O id do recurso, como devolvido pela listagem.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Revogada" }, "401": { "description": "`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`so_sessao` — A rota é de gestão da própria chave (criar, listar, revogar) e foi chamada com chave de API — chave não cria chave.\n\n`cross_site` — Request com sessão vinda de outro site por script (fetch/XHR). Só o próprio app pode usar a sessão.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "so_sessao": { "$ref": "#/components/examples/so_sessao" }, "cross_site": { "$ref": "#/components/examples/cross_site" } } } } }, "404": { "description": "`nao_encontrado` — O recurso não existe — ou pertence a outro workspace, que responde igual (não revelamos que o id é válido).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "nao_encontrado": { "$ref": "#/components/examples/nao_encontrado" } } } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } } } } }, "/api/v1/perfil": { "get": { "operationId": "perfil.ler", "tags": [ "Conta" ], "summary": "Ler o perfil do negócio", "description": "O perfil que alimenta a pesquisa (intent/keywords), o contexto da IA e o texto do comentário→DM.\n\n**Escopo:** `leitura` · **Custo:** grátis · **Limite:** 120 por 60 s", "security": [ { "chave": [ "leitura" ] } ], "x-escopo": "leitura", "x-classe": "leitura", "x-custo": "grátis", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "perfil": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "versao": { "type": "number" }, "completo": { "type": "boolean" }, "atualizadoEm": { "type": "string", "description": "Instante em ISO-8601 UTC, ex. 2026-09-11T12:00:00.000Z" }, "nome": { "type": "string" } }, "required": [ "id", "tenantId", "versao", "completo", "atualizadoEm", "nome" ], "additionalProperties": {}, "description": "O perfil do negócio (PerfilInput + metadados). Campos completos em PUT /v1/perfil" }, { "type": "null" } ] }, "completo": { "type": "boolean" } }, "required": [ "perfil", "completo" ], "additionalProperties": false } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } } } }, "put": { "operationId": "perfil.salvar", "tags": [ "Conta" ], "summary": "Salvar o perfil do negócio", "description": "O mesmo formulário da tela (`PerfilInput`). Cada salvamento sobe a versão. A palavra-chave e o CTA do direct são copiados para a brand do motor.\n\n**Escopo:** `escrita` · **Custo:** grátis · **Limite:** 30 por 60 s", "security": [ { "chave": [ "escrita" ] } ], "x-escopo": "escrita", "x-classe": "escrita", "x-custo": "grátis", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PerfilInput" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "perfil": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "versao": { "type": "number" }, "completo": { "type": "boolean" }, "atualizadoEm": { "type": "string", "description": "Instante em ISO-8601 UTC, ex. 2026-09-11T12:00:00.000Z" }, "nome": { "type": "string" } }, "required": [ "id", "tenantId", "versao", "completo", "atualizadoEm", "nome" ], "additionalProperties": {}, "description": "O perfil do negócio (PerfilInput + metadados). Campos completos em PUT /v1/perfil" }, "completo": { "type": "boolean" }, "brandEspelhada": { "type": "boolean" } }, "required": [ "perfil", "completo", "brandEspelhada" ], "additionalProperties": false } } } }, "400": { "description": "`corpo_invalido` — O JSON não é válido ou não passa na validação do campo (o `detail` diz qual).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "corpo_invalido": { "$ref": "#/components/examples/corpo_invalido" } } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } } } } }, "/api/v1/custo": { "get": { "operationId": "custo.ler", "tags": [ "Conta" ], "summary": "Extrato do mês e teto", "description": "Toda chamada paga aparece aqui com o valor real cobrado pela fonte (`x-cost`).\n\n**Escopo:** `leitura` · **Custo:** grátis · **Limite:** 120 por 60 s", "security": [ { "chave": [ "leitura" ] } ], "x-escopo": "leitura", "x-classe": "leitura", "x-custo": "grátis", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustoDoMes" } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } } } } }, "/api/v1/custo/teto": { "put": { "operationId": "custo.teto", "tags": [ "Conta" ], "summary": "Ajustar o teto de gasto do mês", "description": "As chaves respeitam o mesmo teto da conta. `null` remove o teto. Zero bloqueia tudo que é pago.\n\n**Escopo:** `escrita` · **Custo:** grátis · **Limite:** 30 por 60 s", "security": [ { "chave": [ "escrita" ] } ], "x-escopo": "escrita", "x-classe": "escrita", "x-custo": "grátis", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TetoEntrada" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "teto": { "type": "object", "properties": { "usdMes": { "description": "null = sem teto", "type": [ "number", "null" ] }, "gastoNoMesUsd": { "type": "number" } }, "required": [ "usdMes", "gastoNoMesUsd" ], "additionalProperties": false } }, "required": [ "teto" ], "additionalProperties": false } } } }, "400": { "description": "`corpo_invalido` — O JSON não é válido ou não passa na validação do campo (o `detail` diz qual).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "corpo_invalido": { "$ref": "#/components/examples/corpo_invalido" } } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } } } } }, "/api/v1/conexoes": { "get": { "operationId": "conexoes.ler", "tags": [ "Conta" ], "summary": "Redes conectadas e o que cada uma permite", "description": "Por rede: conectada?, validade do token, e as capacidades reais (publicar, ler comentário, private reply, link na DM). TikTok não tem comentário→DM; a API diz isso em vez de falhar depois.\n\n**Escopo:** `leitura` · **Custo:** grátis · **Limite:** 120 por 60 s", "security": [ { "chave": [ "leitura" ] } ], "x-escopo": "leitura", "x-classe": "leitura", "x-custo": "grátis", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conexoes" } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "404": { "description": "`nao_encontrado` — O recurso não existe — ou pertence a outro workspace, que responde igual (não revelamos que o id é válido).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "nao_encontrado": { "$ref": "#/components/examples/nao_encontrado" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } } } } }, "/api/v1/conexoes/{rede}": { "post": { "operationId": "conexoes.iniciar", "tags": [ "Conta" ], "summary": "Começar a conexão de uma rede", "description": "Devolve a URL de autorização. A pessoa abre no navegador, autoriza, e a conta aparece em GET /v1/conexoes. A API não faz OAuth em nome de ninguém.\n\n**Escopo:** `escrita` · **Custo:** grátis · **Limite:** 30 por 60 s", "security": [ { "chave": [ "escrita" ] } ], "x-escopo": "escrita", "x-classe": "escrita", "x-custo": "grátis", "parameters": [ { "name": "rede", "in": "path", "required": true, "description": "instagram, tiktok ou youtube", "schema": { "type": "string", "enum": [ "instagram", "tiktok", "youtube" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conexao" } } } }, "400": { "description": "`rede_invalida` — A rede não é instagram, tiktok ou youtube.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "rede_invalida": { "$ref": "#/components/examples/rede_invalida" } } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).\n\n`termo_pendente` — A pessoa dona da chave ainda não aceitou o termo de conexão de contas (versão vigente) no app.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" }, "termo_pendente": { "$ref": "#/components/examples/termo_pendente" } } } } }, "409": { "description": "`ponte_nao_configurada` — A chave da ponte de publicação não está no ambiente.\n\n`conexao_recusada` — A ponte de publicação não iniciou a conexão da rede (limite de perfis do plano, brand inválida, ponte fora). O `detail` traz o motivo e `codigoDaPonte` o código dela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "ponte_nao_configurada": { "$ref": "#/components/examples/ponte_nao_configurada" }, "conexao_recusada": { "$ref": "#/components/examples/conexao_recusada" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } } } } }, "/api/v1/clientes": { "get": { "operationId": "clientes.ler", "tags": [ "Conta" ], "summary": "Workspaces que o operador vê", "description": "Normalmente um só (o seu). O `id` é o `clientId` das outras rotas.\n\n**Escopo:** `leitura` · **Custo:** grátis · **Limite:** 120 por 60 s", "security": [ { "chave": [ "leitura" ] } ], "x-escopo": "leitura", "x-classe": "leitura", "x-custo": "grátis", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "itens": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "É o tenant id — o `clientId` das outras rotas" }, "name": { "type": "string" }, "handle": { "type": "string" }, "nicheId": { "type": "string" }, "nicheLabel": { "type": "string" }, "networks": { "type": "array", "items": { "type": "object", "properties": { "network": { "type": "string", "enum": [ "instagram", "tiktok", "youtube" ] }, "connected": { "type": "boolean" }, "status": { "type": "string", "enum": [ "alive", "expiring", "dead", "missing" ] }, "tokenExpiresAt": { "type": "string", "description": "Instante em ISO-8601 UTC, ex. 2026-09-11T12:00:00.000Z" }, "canPublish": { "type": "boolean" }, "canReadComments": { "type": "boolean" }, "canStartDm": { "type": "boolean" }, "canPrivateReply": { "type": "boolean" }, "dmAllowsLinks": { "type": "boolean" }, "handle": { "type": "string" }, "viaSocialApi": { "type": "boolean" } }, "required": [ "network", "connected", "status", "canPublish", "canReadComments", "canStartDm", "canPrivateReply", "dmAllowsLinks" ], "additionalProperties": false } }, "monthlyFeeBrl": { "type": [ "number", "null" ] }, "createdAt": { "type": "string", "description": "Instante em ISO-8601 UTC, ex. 2026-09-11T12:00:00.000Z" }, "perfilCompleto": { "type": "boolean" } }, "required": [ "id", "name", "handle", "nicheLabel", "networks", "monthlyFeeBrl", "createdAt" ], "additionalProperties": false } } }, "required": [ "itens" ], "additionalProperties": false } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } } } } }, "/api/v1/hoje": { "get": { "operationId": "hoje.ler", "tags": [ "Conta" ], "summary": "A fila do dia", "description": "O que precisa de atenção agora: token vencendo, pesquisa pronta, lead com janela fechando. Só itens com fonte real — fila com item falso é pior que fila curta.\n\n**Escopo:** `leitura` · **Custo:** grátis · **Limite:** 120 por 60 s", "security": [ { "chave": [ "leitura" ] } ], "x-escopo": "leitura", "x-classe": "leitura", "x-custo": "grátis", "parameters": [ { "name": "clientId", "in": "query", "required": false, "schema": { "description": "Filtra por workspace", "type": "string" }, "description": "Filtra por workspace" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "itens": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "clientId": { "type": "string" }, "kind": { "type": "string", "enum": [ "piece_review", "lead_reply", "window_closing", "token_expiring", "niche_ready" ] }, "title": { "type": "string" }, "detail": { "type": "string" }, "href": { "type": "string" }, "dueInHours": { "type": "number" }, "severity": { "type": "string", "enum": [ "now", "today", "soon" ] } }, "required": [ "id", "clientId", "kind", "title", "detail", "href", "severity" ], "additionalProperties": false } } }, "required": [ "itens" ], "additionalProperties": false } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } } } } }, "/api/v1/semana": { "get": { "operationId": "semana.ler", "tags": [ "Ciclo" ], "summary": "Os posts desta semana da própria conta", "description": "A semana que o Pico decidiu para a conta da pessoa (o @ do Perfil): 1 Reel + 2 carrosséis, cada um com dia e hora, a ideia inteira (abertura, o que mostrar, fechar, por quê, provas), o estado (prévia, em produção, pronta, montada, agendada, publicada) e o link da peça no app, onde a pessoa aprova. Semeia o calendário a partir do \"O que postar\" já montado; sem nada montado, `proximoPasso` diz o que fazer (POST /v1/semana).\n\n**Escopo:** `leitura` · **Custo:** grátis · **Limite:** 120 por 60 s", "security": [ { "chave": [ "leitura" ] } ], "x-escopo": "leitura", "x-classe": "leitura", "x-custo": "grátis", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "handle": { "type": "string" }, "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "quando": { "type": "string", "description": "Quando sai, ISO" }, "dia": { "type": "string", "description": "O dia e a hora por extenso, em Brasília" }, "tipo": { "type": "string", "description": "Reel com o seu avatar · Reel · Carrossel" }, "formato": { "type": "string", "enum": [ "reel", "carrossel" ] }, "titulo": { "type": "string" }, "estado": { "type": "string", "enum": [ "previa", "em_producao", "pronta", "montada", "agendada", "publicada", "falhou" ] }, "oQueFazer": { "type": "string", "description": "O próximo passo DA PESSOA, em frase de gente — o agente repassa, não executa" }, "link": { "type": "string", "description": "A peça no app, onde a pessoa aprova" }, "ideia": { "anyOf": [ { "type": "object", "properties": { "abertura": { "type": "string", "description": "A primeira frase (falada, ou a 1ª tela do carrossel)" }, "mostrar": { "type": "array", "items": { "type": "string" }, "description": "O que aparece na tela, em passos" }, "fechar": { "type": "string", "description": "Como termina: a chamada" }, "porque": { "type": "string", "description": "Por que este post, montado do dado (nunca inventado)" }, "base": { "type": "string", "description": "Em que se apoia: J1… (um jeito do nicho) ou V1… (um viral)" }, "provas": { "type": "array", "items": { "type": "object", "properties": { "conta": { "type": "string" }, "vezes": { "type": "number" } }, "required": [ "conta", "vezes" ], "additionalProperties": false }, "description": "As contas e quantas vezes o normal cada exemplo rendeu" } }, "required": [ "abertura", "mostrar", "fechar", "porque", "base", "provas" ], "additionalProperties": false }, { "type": "null" } ], "description": "A ideia inteira enquanto a peça ainda a carrega; null na peça já montada no Criar" } }, "required": [ "id", "quando", "dia", "tipo", "formato", "titulo", "estado", "oQueFazer", "link", "ideia" ], "additionalProperties": false } }, "calendario": { "type": "string", "description": "O Meu Calendário no app" }, "proximoPasso": { "description": "Preenchido quando a semana veio vazia", "type": [ "string", "null" ] } }, "required": [ "handle", "posts", "calendario", "proximoPasso" ], "additionalProperties": false } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "404": { "description": "`nao_encontrado` — O recurso não existe — ou pertence a outro workspace, que responde igual (não revelamos que o id é válido).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "nao_encontrado": { "$ref": "#/components/examples/nao_encontrado" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } } } }, "post": { "operationId": "semana.montar", "tags": [ "Ciclo" ], "summary": "Montar a semana agora", "description": "Pede à IA do Pico os posts da semana para a própria conta (o mesmo \"O que postar\" do Início), semeia o calendário e devolve a semana. Conta como 1 análise de IA do dia do plano da pessoa. Use só quando GET /v1/semana vier sem posts.\n\n**Escopo:** `gasto` · **Custo:** IA do Pico · **Limite:** 6 por 60 s", "security": [ { "chave": [ "gasto" ] } ], "x-escopo": "gasto", "x-classe": "gasto", "x-custo": "IA do Pico", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "handle": { "type": "string" }, "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "quando": { "type": "string", "description": "Quando sai, ISO" }, "dia": { "type": "string", "description": "O dia e a hora por extenso, em Brasília" }, "tipo": { "type": "string", "description": "Reel com o seu avatar · Reel · Carrossel" }, "formato": { "type": "string", "enum": [ "reel", "carrossel" ] }, "titulo": { "type": "string" }, "estado": { "type": "string", "enum": [ "previa", "em_producao", "pronta", "montada", "agendada", "publicada", "falhou" ] }, "oQueFazer": { "type": "string", "description": "O próximo passo DA PESSOA, em frase de gente — o agente repassa, não executa" }, "link": { "type": "string", "description": "A peça no app, onde a pessoa aprova" }, "ideia": { "anyOf": [ { "type": "object", "properties": { "abertura": { "type": "string", "description": "A primeira frase (falada, ou a 1ª tela do carrossel)" }, "mostrar": { "type": "array", "items": { "type": "string" }, "description": "O que aparece na tela, em passos" }, "fechar": { "type": "string", "description": "Como termina: a chamada" }, "porque": { "type": "string", "description": "Por que este post, montado do dado (nunca inventado)" }, "base": { "type": "string", "description": "Em que se apoia: J1… (um jeito do nicho) ou V1… (um viral)" }, "provas": { "type": "array", "items": { "type": "object", "properties": { "conta": { "type": "string" }, "vezes": { "type": "number" } }, "required": [ "conta", "vezes" ], "additionalProperties": false }, "description": "As contas e quantas vezes o normal cada exemplo rendeu" } }, "required": [ "abertura", "mostrar", "fechar", "porque", "base", "provas" ], "additionalProperties": false }, { "type": "null" } ], "description": "A ideia inteira enquanto a peça ainda a carrega; null na peça já montada no Criar" } }, "required": [ "id", "quando", "dia", "tipo", "formato", "titulo", "estado", "oQueFazer", "link", "ideia" ], "additionalProperties": false } }, "calendario": { "type": "string", "description": "O Meu Calendário no app" }, "proximoPasso": { "description": "Preenchido quando a semana veio vazia", "type": [ "string", "null" ] } }, "required": [ "handle", "posts", "calendario", "proximoPasso" ], "additionalProperties": false } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "404": { "description": "`nao_encontrado` — O recurso não existe — ou pertence a outro workspace, que responde igual (não revelamos que o id é válido).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "nao_encontrado": { "$ref": "#/components/examples/nao_encontrado" } } } } }, "409": { "description": "`limite_do_plano` — O plano do workspace (Grátis, Pro ou Agência) não comporta mais um deste recurso — nichos, posts, criações, marcas, concorrentes — ou não inclui a ação (publicar no Grátis). O `detail` diz o uso, o limite e o plano que destrava.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_do_plano": { "$ref": "#/components/examples/limite_do_plano" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } }, "502": { "description": "`ia_indisponivel` — O provedor de IA falhou ou está sem crédito.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "ia_indisponivel": { "$ref": "#/components/examples/ia_indisponivel" } } } } } } } }, "/api/v1/conta": { "get": { "operationId": "conta.ler", "tags": [ "Ciclo" ], "summary": "A própria conta de relance", "description": "A conta da pessoa como o Pico a lê: perfil e últimos posts com quantas vezes o normal da própria conta cada um rendeu (`vezes`), a série das leituras (seguidores e o vídeo normal, antes e depois), quantos posts da semana estão no calendário e o link do Início (onde está o benchmark contra contas do mesmo tamanho). Sem leitura ainda, 404 com o próximo passo.\n\n**Escopo:** `leitura` · **Custo:** grátis · **Limite:** 120 por 60 s", "security": [ { "chave": [ "leitura" ] } ], "x-escopo": "leitura", "x-classe": "leitura", "x-custo": "grátis", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "handle": { "type": "string" }, "conta": { "anyOf": [ { "type": "object", "properties": { "handle": { "type": "string" }, "rede": { "type": "string", "const": "instagram" }, "url": { "type": "string" }, "lidoEm": { "type": [ "string", "null" ] }, "reaproveitado": { "type": "boolean", "description": "true = não custou nada agora" }, "perfil": { "type": "object", "properties": { "nome": { "type": "string" }, "bio": { "type": "string" }, "site": { "type": "string" }, "categoria": { "type": "string" }, "seguidores": { "type": [ "number", "null" ] }, "seguindo": { "type": [ "number", "null" ] }, "posts": { "type": [ "number", "null" ] }, "verificado": { "type": "boolean" }, "contaComercial": { "type": "boolean" }, "foto": { "type": "string" } }, "required": [ "nome", "bio", "site", "categoria", "seguidores", "seguindo", "posts", "verificado", "contaComercial", "foto" ], "additionalProperties": false }, "contatos": { "type": "object", "properties": { "whatsapp": { "type": "array", "items": { "type": "string" } }, "telefones": { "type": "array", "items": { "type": "string" } }, "emails": { "type": "array", "items": { "type": "string" } }, "links": { "type": "array", "items": { "type": "string" } } }, "required": [ "whatsapp", "telefones", "emails", "links" ], "additionalProperties": false }, "ritmo": { "type": "object", "properties": { "amostra": { "type": "number" }, "postsPorSemana": { "type": [ "number", "null" ] }, "curtidasMediana": { "type": [ "number", "null" ] }, "comentariosMediana": { "type": [ "number", "null" ] }, "viewsMediana": { "type": [ "number", "null" ] }, "formatos": { "type": "object", "properties": { "reel": { "type": "number" }, "carrossel": { "type": "number" }, "imagem": { "type": "number" } }, "required": [ "reel", "carrossel", "imagem" ], "additionalProperties": false } }, "required": [ "amostra", "postsPorSemana", "curtidasMediana", "comentariosMediana", "viewsMediana", "formatos" ], "additionalProperties": false }, "posts": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "tipo": { "type": "string", "enum": [ "reel", "imagem", "carrossel" ] }, "data": { "type": [ "string", "null" ] }, "curtidas": { "type": [ "number", "null" ] }, "comentarios": { "type": [ "number", "null" ] }, "views": { "description": "Plays — só Reel", "type": [ "number", "null" ] }, "vezes": { "description": "Quantas vezes o normal da própria conta (views nos Reels, curtidas nos demais)", "type": [ "number", "null" ] }, "fixado": { "type": "boolean" }, "legenda": { "type": "string" }, "legendaCortada": { "type": "boolean" }, "hashtags": { "type": "array", "items": { "type": "string" } }, "imagens": { "type": "array", "items": { "type": "string" }, "description": "Links do CDN do Instagram — vencem em 2 a 5 dias" } }, "required": [ "url", "tipo", "data", "curtidas", "comentarios", "views", "vezes", "fixado", "legenda", "legendaCortada", "hashtags", "imagens" ], "additionalProperties": false } }, "destaques": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "tipo": { "type": "string", "enum": [ "reel", "imagem", "carrossel" ] }, "vezes": { "type": "number" }, "legenda": { "type": "string" } }, "required": [ "url", "tipo", "vezes", "legenda" ], "additionalProperties": false } }, "avisos": { "type": "array", "items": { "type": "string" } }, "custo": { "type": "object", "properties": { "usd": { "type": "number" } }, "required": [ "usd" ], "additionalProperties": false } }, "required": [ "handle", "rede", "url", "lidoEm", "reaproveitado", "perfil", "contatos", "ritmo", "posts", "destaques", "avisos" ], "additionalProperties": false }, { "type": "null" } ], "description": "A última leitura da conta (até 30 dias): perfil, posts com `vezes`, destaques" }, "serie": { "anyOf": [ { "type": "object", "properties": { "fotos": { "type": "number", "description": "Quantas leituras a conta tem" }, "periodo": { "type": "object", "properties": { "de": { "type": "string" }, "ate": { "type": "string" }, "dias": { "type": "number" } }, "required": [ "de", "ate", "dias" ], "additionalProperties": false }, "seguidores": { "anyOf": [ { "type": "object", "properties": { "antes": { "type": "number" }, "depois": { "type": "number" }, "razao": { "type": [ "number", "null" ] } }, "required": [ "antes", "depois", "razao" ], "additionalProperties": false }, { "type": "null" } ] }, "normal": { "anyOf": [ { "type": "object", "properties": { "antes": { "type": "number" }, "depois": { "type": "number" }, "razao": { "type": [ "number", "null" ] } }, "required": [ "antes", "depois", "razao" ], "additionalProperties": false }, { "type": "null" } ], "description": "O vídeo normal (mediana de views dos Reels) na 1ª e na última leitura" }, "virais": { "type": "number", "description": "Posts que passaram muito do normal da conta no período" } }, "required": [ "fotos", "periodo", "seguidores", "normal", "virais" ], "additionalProperties": false }, { "type": "null" } ] }, "semana": { "type": "object", "properties": { "posts": { "type": "number" }, "link": { "type": "string" } }, "required": [ "posts", "link" ], "additionalProperties": false }, "inicio": { "type": "string", "description": "O Início do app, onde está o benchmark contra contas do mesmo tamanho" } }, "required": [ "handle", "conta", "serie", "semana", "inicio" ], "additionalProperties": false } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "404": { "description": "`nao_encontrado` — O recurso não existe — ou pertence a outro workspace, que responde igual (não revelamos que o id é válido).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "nao_encontrado": { "$ref": "#/components/examples/nao_encontrado" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } } } } }, "/api/v1/funcionou": { "get": { "operationId": "funcionou.ler", "tags": [ "Ciclo" ], "summary": "A dica funcionou?", "description": "Das indicações que o Pico fez à conta da pessoa: quantas fecharam, a frase de cada veredito (postou, usou a dica, passou o normal da própria conta) e quando a próxima pode fechar. O veredito sai em até 42 dias (28 para a pessoa postar, 14 para o post amadurecer); antes disso é \"em espera\", nunca número inventado.\n\n**Escopo:** `leitura` · **Custo:** grátis · **Limite:** 120 por 60 s", "security": [ { "chave": [ "leitura" ] } ], "x-escopo": "leitura", "x-classe": "leitura", "x-custo": "grátis", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "handle": { "type": "string" }, "registradas": { "type": "number" }, "emEspera": { "type": "number" }, "primeiroVereditoEm": { "type": [ "string", "null" ] }, "fechadas": { "type": "array", "items": { "type": "object", "properties": { "rotulo": { "type": "string" }, "veredito": { "type": "string" }, "frase": { "type": "string" }, "fator": { "type": [ "number", "null" ] }, "indicadaEm": { "type": "string" } }, "required": [ "rotulo", "veredito", "frase", "fator", "indicadaEm" ], "additionalProperties": false } }, "comoLer": { "type": "string" } }, "required": [ "handle", "registradas", "emEspera", "primeiroVereditoEm", "fechadas", "comoLer" ], "additionalProperties": false } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "404": { "description": "`nao_encontrado` — O recurso não existe — ou pertence a outro workspace, que responde igual (não revelamos que o id é válido).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "nao_encontrado": { "$ref": "#/components/examples/nao_encontrado" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } } } } }, "/api/v1/pesquisas": { "get": { "operationId": "pesquisas.listar", "tags": [ "Pesquisas" ], "summary": "Listar pesquisas", "description": "Os cartões (sem o resultado inteiro), mais nova primeiro. Paginação por cursor.\n\n**Escopo:** `leitura` · **Custo:** grátis · **Limite:** 120 por 60 s", "security": [ { "chave": [ "leitura" ] } ], "x-escopo": "leitura", "x-classe": "leitura", "x-custo": "grátis", "parameters": [ { "name": "limite", "in": "query", "required": false, "schema": { "description": "Itens por página (padrão 50)", "type": "integer", "minimum": 1, "maximum": 200 }, "description": "Itens por página (padrão 50)" }, { "name": "cursor", "in": "query", "required": false, "schema": { "description": "O `proximoCursor` da página anterior", "type": "string" }, "description": "O `proximoCursor` da página anterior" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "itens": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "nome": { "type": "string" }, "intent": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" } }, "excludeKeywords": { "type": "array", "items": { "type": "string" } }, "platforms": { "type": "array", "items": { "type": "string", "enum": [ "instagram", "tiktok", "youtube" ] } }, "status": { "type": "string", "enum": [ "idle", "running", "completed", "failed" ] }, "progresso": { "type": [ "number", "null" ] }, "etapa": { "type": [ "string", "null" ] }, "criadoEm": { "type": "string", "description": "Instante em ISO-8601 UTC, ex. 2026-09-11T12:00:00.000Z" }, "ultimaRodadaEm": { "anyOf": [ { "type": "string", "description": "Instante em ISO-8601 UTC, ex. 2026-09-11T12:00:00.000Z" }, { "type": "null" } ] }, "custoUsd": { "type": [ "number", "null" ] }, "dataIntelligence": { "type": "boolean" }, "metaAds": { "type": "boolean" }, "recorrente": { "type": "boolean" }, "cadencia": { "type": [ "string", "null" ] }, "fonteId": { "type": [ "string", "null" ] }, "contagens": { "anyOf": [ { "type": "object", "properties": { "videos": { "type": "number" }, "videosTotal": { "type": "number" }, "criadores": { "type": "number" }, "ganchos": { "type": "number" }, "sons": { "type": "number" }, "hashtags": { "type": "number" }, "anuncios": { "type": "number" }, "tendencias": { "type": "number" }, "benchmarks": { "type": "number" }, "analise": { "type": "boolean" } }, "required": [ "videos", "videosTotal", "criadores", "ganchos", "sons", "hashtags", "anuncios", "tendencias", "benchmarks", "analise" ], "additionalProperties": false }, { "type": "null" } ], "description": "null enquanto não há resultado" }, "traducao": { "anyOf": [ { "type": "object", "properties": { "total": { "type": "number" }, "traduzidas": { "type": "number" } }, "required": [ "total", "traduzidas" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "nome", "intent", "keywords", "excludeKeywords", "platforms", "status", "progresso", "etapa", "criadoEm", "ultimaRodadaEm", "custoUsd", "dataIntelligence", "metaAds", "recorrente", "cadencia", "fonteId", "contagens", "traducao" ], "additionalProperties": false } }, "proximoCursor": { "description": "Passe em ?cursor= para a próxima página", "type": [ "string", "null" ] } }, "required": [ "itens", "proximoCursor" ], "additionalProperties": false } } } }, "400": { "description": "`parametro_invalido` — Um parâmetro de caminho ou de query está fora do formato (id, cursor, data).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "parametro_invalido": { "$ref": "#/components/examples/parametro_invalido" } } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } } } }, "post": { "operationId": "pesquisas.criar", "tags": [ "Pesquisas" ], "summary": "Pesquisar um nicho", "description": "Cria a coleta na fonte e grava a pesquisa com status `running`. Depois, chame GET /v1/pesquisas/{id} até `completed` — é esse GET que avança o estado. Custa US$ 0,50 (coleta) + US$ 1,00 com inteligência por vídeo (ganchos, tópicos). Sem `confirmarGasto: true` responde 409 com a estimativa e não cobra nada.\n\n**Escopo:** `gasto` · **Custo:** US$ 0,50 + US$ 1,00 com inteligência · **Limite:** 6 por 60 s\n**Confirmação:** o corpo tem que trazer `\"confirmarGasto\": true` literal.\n**Idempotência:** aceita o header `Idempotency-Key` (repetição em 24 h devolve a mesma resposta).", "security": [ { "chave": [ "gasto" ] } ], "x-escopo": "gasto", "x-classe": "gasto", "x-custo": "US$ 0,50 + US$ 1,00 com inteligência", "x-confirmacao": "confirmarGasto", "x-idempotencia": true, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Um UUID por operação. Repetir com o mesmo valor em 24 h devolve a resposta gravada, sem cobrar de novo.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CriarPesquisaEntrada" } } } }, "responses": { "202": { "description": "Criada e rodando", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PesquisaCriada" } } } }, "400": { "description": "`corpo_invalido` — O JSON não é válido ou não passa na validação do campo (o `detail` diz qual).\n\n`idempotencia_invalida` — O header veio vazio ou com mais de 200 caracteres.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "corpo_invalido": { "$ref": "#/components/examples/corpo_invalido" }, "idempotencia_invalida": { "$ref": "#/components/examples/idempotencia_invalida" } } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "409": { "description": "`gasto_nao_confirmado` — A rota cobra da conta (fonte ou IA) e o corpo não trouxe `confirmarGasto: true`. O `detail` diz o valor.\n\n`teto_do_mes` — A chamada estouraria o teto de gasto do mês configurado em Conta → Custo.\n\n`limite_do_plano` — O plano do workspace (Grátis, Pro ou Agência) não comporta mais um deste recurso — nichos, posts, criações, marcas, concorrentes — ou não inclui a ação (publicar no Grátis). O `detail` diz o uso, o limite e o plano que destrava.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "gasto_nao_confirmado": { "$ref": "#/components/examples/gasto_nao_confirmado" }, "teto_do_mes": { "$ref": "#/components/examples/teto_do_mes" }, "limite_do_plano": { "$ref": "#/components/examples/limite_do_plano" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } }, "502": { "description": "`fonte_indisponivel` — A fonte falhou ou a chave dela está ausente/sem saldo.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "fonte_indisponivel": { "$ref": "#/components/examples/fonte_indisponivel" } } } } } } } }, "/api/v1/pesquisas/taxonomias": { "get": { "operationId": "pesquisas.taxonomias", "tags": [ "Pesquisas" ], "summary": "Tipos de gancho, categorias e regiões", "description": "As taxonomias da fonte (grátis). Útil para interpretar `hookType` e filtrar.\n\n**Escopo:** `leitura` · **Custo:** grátis · **Limite:** 120 por 60 s", "security": [ { "chave": [ "leitura" ] } ], "x-escopo": "leitura", "x-classe": "leitura", "x-custo": "grátis", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Taxonomias" } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } }, "502": { "description": "`fonte_indisponivel` — A fonte falhou ou a chave dela está ausente/sem saldo.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "fonte_indisponivel": { "$ref": "#/components/examples/fonte_indisponivel" } } } } } } } }, "/api/v1/pesquisas/sugerir-keywords": { "post": { "operationId": "pesquisas.sugerirKeywords", "tags": [ "Pesquisas" ], "summary": "Sugerir palavras-chave a partir do intent", "description": "Grátis. Devolve keywords, exclusões e um julgamento de qualidade da fonte.\n\n**Escopo:** `leitura` · **Custo:** grátis (reasoning traduzido pela IA do Pico) · **Limite:** 120 por 60 s", "security": [ { "chave": [ "leitura" ] } ], "x-escopo": "leitura", "x-classe": "leitura", "x-custo": "grátis (reasoning traduzido pela IA do Pico)", "parameters": [ { "name": "idioma", "in": "query", "required": false, "schema": { "default": "pt", "type": "string", "enum": [ "pt", "en" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SugerirKeywordsEntrada" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Keywords" } } } }, "400": { "description": "`corpo_invalido` — O JSON não é válido ou não passa na validação do campo (o `detail` diz qual).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "corpo_invalido": { "$ref": "#/components/examples/corpo_invalido" } } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } }, "502": { "description": "`fonte_indisponivel` — A fonte falhou ou a chave dela está ausente/sem saldo.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "fonte_indisponivel": { "$ref": "#/components/examples/fonte_indisponivel" } } } } } } } }, "/api/v1/pesquisas/melhorar-intent": { "post": { "operationId": "pesquisas.melhorarIntent", "tags": [ "Pesquisas" ], "summary": "Reescrever uma descrição crua como frase de pesquisa", "description": "IA do Pico (sem custo para a sua conta). Usa o perfil do negócio para completar público/região/produto — só o que está nele.\n\n**Escopo:** `gasto` · **Custo:** IA do Pico · **Limite:** 6 por 60 s", "security": [ { "chave": [ "gasto" ] } ], "x-escopo": "gasto", "x-classe": "gasto", "x-custo": "IA do Pico", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MelhorarIntentEntrada" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntentMelhorado" } } } }, "400": { "description": "`corpo_invalido` — O JSON não é válido ou não passa na validação do campo (o `detail` diz qual).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "corpo_invalido": { "$ref": "#/components/examples/corpo_invalido" } } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } }, "502": { "description": "`ia_indisponivel` — O provedor de IA falhou ou está sem crédito.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "ia_indisponivel": { "$ref": "#/components/examples/ia_indisponivel" } } } } } } } }, "/api/v1/pesquisas/{id}": { "get": { "operationId": "pesquisas.ler", "tags": [ "Pesquisas" ], "summary": "Estado de uma pesquisa (e avança se estiver rodando)", "description": "Se `running`, faz o poll na fonte; terminou → hidrata, grava e devolve `completed`. É o único jeito de a pesquisa avançar — não há cron. Chame a cada ~5 s.\n\n**Escopo:** `leitura` · **Custo:** grátis · **Limite:** 120 por 60 s", "security": [ { "chave": [ "leitura" ] } ], "x-escopo": "leitura", "x-classe": "leitura", "x-custo": "grátis", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "O id do recurso, como devolvido pela listagem.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PesquisaCartao" } } } }, "400": { "description": "`parametro_invalido` — Um parâmetro de caminho ou de query está fora do formato (id, cursor, data).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "parametro_invalido": { "$ref": "#/components/examples/parametro_invalido" } } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "404": { "description": "`nao_encontrado` — O recurso não existe — ou pertence a outro workspace, que responde igual (não revelamos que o id é válido).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "nao_encontrado": { "$ref": "#/components/examples/nao_encontrado" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } } } } }, "/api/v1/pesquisas/{id}/{recurso}": { "get": { "operationId": "pesquisas.recurso", "tags": [ "Pesquisas" ], "summary": "Um recorte do resultado", "description": "`videos` (por Virality Score), `criadores`, `ganchos`, `sons`, `hashtags`, `anuncios`, `analise`, `benchmarks`, `tendencias`, `resumo`. `?idioma=pt` (padrão) aplica a tradução gravada; `traducao` diz a cobertura — se faltar, POST …/traduzir.\n\n**Escopo:** `leitura` · **Custo:** grátis · **Limite:** 120 por 60 s", "security": [ { "chave": [ "leitura" ] } ], "x-escopo": "leitura", "x-classe": "leitura", "x-custo": "grátis", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "O id do recurso, como devolvido pela listagem.", "schema": { "type": "string" } }, { "name": "recurso", "in": "path", "required": true, "description": "Qual recorte", "schema": { "type": "string", "enum": [ "videos", "criadores", "ganchos", "sons", "hashtags", "anuncios", "analise", "benchmarks", "tendencias", "resumo" ] } }, { "name": "idioma", "in": "query", "required": false, "schema": { "default": "pt", "type": "string", "enum": [ "pt", "en" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Recurso" } } } }, "400": { "description": "`parametro_invalido` — Um parâmetro de caminho ou de query está fora do formato (id, cursor, data).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "parametro_invalido": { "$ref": "#/components/examples/parametro_invalido" } } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "404": { "description": "`nao_encontrado` — O recurso não existe — ou pertence a outro workspace, que responde igual (não revelamos que o id é válido).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "nao_encontrado": { "$ref": "#/components/examples/nao_encontrado" } } } } }, "409": { "description": "`pesquisa_em_andamento` — O resultado pedido ainda não existe: a pesquisa está rodando.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "pesquisa_em_andamento": { "$ref": "#/components/examples/pesquisa_em_andamento" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } } } } }, "/api/v1/pesquisas/{id}/traduzir": { "post": { "operationId": "pesquisas.traduzir", "tags": [ "Pesquisas" ], "summary": "Traduzir a narrativa da fonte para português", "description": "A análise, as tendências e os resumos por vídeo vêm em inglês. Isto traduz o que falta e grava; `hookText` (fala do criador) e títulos ficam como estão. Parcial é resposta normal (202, `completa: false`) — chame de novo. IA do Pico.\n\n**Escopo:** `escrita` · **Custo:** IA do Pico · **Limite:** 30 por 60 s", "security": [ { "chave": [ "escrita" ] } ], "x-escopo": "escrita", "x-classe": "escrita", "x-custo": "IA do Pico", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "O id do recurso, como devolvido pela listagem.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Completa", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelatorioTraducao" } } } }, "202": { "description": "Parcial — chame de novo", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelatorioTraducao" } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "404": { "description": "`nao_encontrado` — O recurso não existe — ou pertence a outro workspace, que responde igual (não revelamos que o id é válido).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "nao_encontrado": { "$ref": "#/components/examples/nao_encontrado" } } } } }, "409": { "description": "`pesquisa_em_andamento` — O resultado pedido ainda não existe: a pesquisa está rodando.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "pesquisa_em_andamento": { "$ref": "#/components/examples/pesquisa_em_andamento" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } }, "502": { "description": "`ia_indisponivel` — O provedor de IA falhou ou está sem crédito.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "ia_indisponivel": { "$ref": "#/components/examples/ia_indisponivel" } } } } } } } }, "/api/v1/pesquisas/{id}/analise": { "post": { "operationId": "pesquisas.analise", "tags": [ "Pesquisas" ], "summary": "Relatório por IA sobre o corpus", "description": "Resumo, temas, estratégia, padrões de gancho e horários — em português, com o perfil do negócio no contexto. Grava em `analise` da pesquisa. IA do Pico.\n\n**Escopo:** `gasto` · **Custo:** IA do Pico · **Limite:** 6 por 60 s", "security": [ { "chave": [ "gasto" ] } ], "x-escopo": "gasto", "x-classe": "gasto", "x-custo": "IA do Pico", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "O id do recurso, como devolvido pela listagem.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Analise" } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "404": { "description": "`nao_encontrado` — O recurso não existe — ou pertence a outro workspace, que responde igual (não revelamos que o id é válido).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "nao_encontrado": { "$ref": "#/components/examples/nao_encontrado" } } } } }, "409": { "description": "`pesquisa_em_andamento` — O resultado pedido ainda não existe: a pesquisa está rodando.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "pesquisa_em_andamento": { "$ref": "#/components/examples/pesquisa_em_andamento" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } }, "502": { "description": "`ia_indisponivel` — O provedor de IA falhou ou está sem crédito.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "ia_indisponivel": { "$ref": "#/components/examples/ia_indisponivel" } } } } } } } }, "/api/v1/criadores": { "get": { "operationId": "criadores.listar", "tags": [ "Criadores" ], "summary": "Satélites e monitorados", "description": "Satélite = consulta pontual de um perfil; monitorado = acompanhamento com cadência.\n\n**Escopo:** `leitura` · **Custo:** grátis · **Limite:** 120 por 60 s", "security": [ { "chave": [ "leitura" ] } ], "x-escopo": "leitura", "x-classe": "leitura", "x-custo": "grátis", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Criadores" } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } } } } }, "/api/v1/criadores/satelite": { "post": { "operationId": "criadores.satelite.criar", "tags": [ "Criadores" ], "summary": "Consultar um perfil (satélite)", "description": "US$ 0,50. Cria o job na fonte e grava; GET /v1/criadores/satelite/{id} faz o poll e grava perfil, vídeos e relatório quando pronto.\n\n**Escopo:** `gasto` · **Custo:** US$ 0,50 · **Limite:** 6 por 60 s\n**Confirmação:** o corpo tem que trazer `\"confirmarGasto\": true` literal.\n**Idempotência:** aceita o header `Idempotency-Key` (repetição em 24 h devolve a mesma resposta).", "security": [ { "chave": [ "gasto" ] } ], "x-escopo": "gasto", "x-classe": "gasto", "x-custo": "US$ 0,50", "x-confirmacao": "confirmarGasto", "x-idempotencia": true, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Um UUID por operação. Repetir com o mesmo valor em 24 h devolve a resposta gravada, sem cobrar de novo.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SateliteEntrada" } } } }, "responses": { "202": { "description": "Job criado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SateliteCriado" } } } }, "400": { "description": "`corpo_invalido` — O JSON não é válido ou não passa na validação do campo (o `detail` diz qual).\n\n`idempotencia_invalida` — O header veio vazio ou com mais de 200 caracteres.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "corpo_invalido": { "$ref": "#/components/examples/corpo_invalido" }, "idempotencia_invalida": { "$ref": "#/components/examples/idempotencia_invalida" } } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "409": { "description": "`gasto_nao_confirmado` — A rota cobra da conta (fonte ou IA) e o corpo não trouxe `confirmarGasto: true`. O `detail` diz o valor.\n\n`teto_do_mes` — A chamada estouraria o teto de gasto do mês configurado em Conta → Custo.\n\n`limite_do_plano` — O plano do workspace (Grátis, Pro ou Agência) não comporta mais um deste recurso — nichos, posts, criações, marcas, concorrentes — ou não inclui a ação (publicar no Grátis). O `detail` diz o uso, o limite e o plano que destrava.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "gasto_nao_confirmado": { "$ref": "#/components/examples/gasto_nao_confirmado" }, "teto_do_mes": { "$ref": "#/components/examples/teto_do_mes" }, "limite_do_plano": { "$ref": "#/components/examples/limite_do_plano" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } }, "502": { "description": "`fonte_indisponivel` — A fonte falhou ou a chave dela está ausente/sem saldo.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "fonte_indisponivel": { "$ref": "#/components/examples/fonte_indisponivel" } } } } } } } }, "/api/v1/criadores/satelite/{id}": { "get": { "operationId": "criadores.satelite.ler", "tags": [ "Criadores" ], "summary": "Um satélite (e avança se estiver processando)", "description": "Poll sob demanda: enquanto processa devolve `status: processing`; pronto devolve perfil, vídeos e relatório e grava.\n\n**Escopo:** `leitura` · **Custo:** grátis · **Limite:** 120 por 60 s", "security": [ { "chave": [ "leitura" ] } ], "x-escopo": "leitura", "x-classe": "leitura", "x-custo": "grátis", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "O id do recurso, como devolvido pela listagem.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Satelite" } } } }, "400": { "description": "`parametro_invalido` — Um parâmetro de caminho ou de query está fora do formato (id, cursor, data).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "parametro_invalido": { "$ref": "#/components/examples/parametro_invalido" } } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "404": { "description": "`nao_encontrado` — O recurso não existe — ou pertence a outro workspace, que responde igual (não revelamos que o id é válido).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "nao_encontrado": { "$ref": "#/components/examples/nao_encontrado" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } } } } }, "/api/v1/criadores/monitorar": { "post": { "operationId": "criadores.monitorar", "tags": [ "Criadores" ], "summary": "Monitorar um criador com cadência", "description": "US$ 0,25 por ciclo de coleta. A fonte revisita o perfil na cadência escolhida.\n\n**Escopo:** `gasto` · **Custo:** US$ 0,25 por ciclo · **Limite:** 6 por 60 s\n**Confirmação:** o corpo tem que trazer `\"confirmarGasto\": true` literal.\n**Idempotência:** aceita o header `Idempotency-Key` (repetição em 24 h devolve a mesma resposta).", "security": [ { "chave": [ "gasto" ] } ], "x-escopo": "gasto", "x-classe": "gasto", "x-custo": "US$ 0,25 por ciclo", "x-confirmacao": "confirmarGasto", "x-idempotencia": true, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Um UUID por operação. Repetir com o mesmo valor em 24 h devolve a resposta gravada, sem cobrar de novo.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorarEntrada" } } } }, "responses": { "202": { "description": "Monitoramento criado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitoradoCriado" } } } }, "400": { "description": "`corpo_invalido` — O JSON não é válido ou não passa na validação do campo (o `detail` diz qual).\n\n`idempotencia_invalida` — O header veio vazio ou com mais de 200 caracteres.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "corpo_invalido": { "$ref": "#/components/examples/corpo_invalido" }, "idempotencia_invalida": { "$ref": "#/components/examples/idempotencia_invalida" } } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "409": { "description": "`gasto_nao_confirmado` — A rota cobra da conta (fonte ou IA) e o corpo não trouxe `confirmarGasto: true`. O `detail` diz o valor.\n\n`teto_do_mes` — A chamada estouraria o teto de gasto do mês configurado em Conta → Custo.\n\n`limite_do_plano` — O plano do workspace (Grátis, Pro ou Agência) não comporta mais um deste recurso — nichos, posts, criações, marcas, concorrentes — ou não inclui a ação (publicar no Grátis). O `detail` diz o uso, o limite e o plano que destrava.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "gasto_nao_confirmado": { "$ref": "#/components/examples/gasto_nao_confirmado" }, "teto_do_mes": { "$ref": "#/components/examples/teto_do_mes" }, "limite_do_plano": { "$ref": "#/components/examples/limite_do_plano" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } }, "502": { "description": "`fonte_indisponivel` — A fonte falhou ou a chave dela está ausente/sem saldo.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "fonte_indisponivel": { "$ref": "#/components/examples/fonte_indisponivel" } } } } } } } }, "/api/v1/criadores/{id}/analise": { "post": { "operationId": "criadores.analise", "tags": [ "Criadores" ], "summary": "Briefing por IA de um criador", "description": "180–260 palavras: categoria, o que funciona, ganchos, cadência, risco de saturação e 3 ações para o SEU negócio. Grava em `report`. IA do Pico.\n\n**Escopo:** `gasto` · **Custo:** IA do Pico · **Limite:** 6 por 60 s", "security": [ { "chave": [ "gasto" ] } ], "x-escopo": "gasto", "x-classe": "gasto", "x-custo": "IA do Pico", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "O id do recurso, como devolvido pela listagem.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Briefing" } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "404": { "description": "`nao_encontrado` — O recurso não existe — ou pertence a outro workspace, que responde igual (não revelamos que o id é válido).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "nao_encontrado": { "$ref": "#/components/examples/nao_encontrado" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } }, "502": { "description": "`ia_indisponivel` — O provedor de IA falhou ou está sem crédito.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "ia_indisponivel": { "$ref": "#/components/examples/ia_indisponivel" } } } } } } } }, "/api/v1/nichos": { "get": { "operationId": "nichos.listar", "tags": [ "Ramos" ], "summary": "Ramos lidos pela esteira", "description": "Todos os ramos (dado público agregado): estado da esteira, quando foi lido, contas, Reels, quantos jeitos de fazer, a régua do tamanho. Custo e log por passo só nos que este workspace pediu (`meu: true`).\n\n**Escopo:** `leitura` · **Custo:** grátis · **Limite:** 120 por 60 s", "security": [ { "chave": [ "leitura" ] } ], "x-escopo": "leitura", "x-classe": "leitura", "x-custo": "grátis", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "itens": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "nome": { "type": "string" }, "estado": { "type": "string", "description": "pedido → ler_bios → aprovar → ler_posts → transcrever → embedar → agrupar → capas → gancho → registrado (ou falhou)" }, "lidoEm": { "type": [ "string", "null" ] }, "contas": { "type": [ "number", "null" ] }, "reels": { "type": [ "number", "null" ] }, "jeitos": { "type": "number" }, "regua": { "anyOf": [ { "type": "object", "properties": { "b1": { "type": "number" }, "r2": { "type": "number" } }, "required": [ "b1", "r2" ], "additionalProperties": false }, { "type": "null" } ] }, "erro": { "type": [ "string", "null" ] }, "atualizadoEm": { "type": "string" }, "meu": { "type": "boolean", "description": "Pedido por este workspace (só então vêm custo e passos)" }, "custoUsd": { "type": [ "number", "null" ] }, "passos": {} }, "required": [ "id", "nome", "estado", "lidoEm", "contas", "reels", "jeitos", "regua", "erro", "atualizadoEm", "meu" ], "additionalProperties": false } } }, "required": [ "itens" ], "additionalProperties": false } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } } } }, "post": { "operationId": "nichos.pedir", "tags": [ "Ramos" ], "summary": "Pedir a leitura de um ramo inteiro", "description": "Entra na fila do tick: bios → aprovação → posts → fala → vetor → jeitos → capas → gancho. Fica `registrado` sozinho em ~1–2 h (acompanhe em GET /v1/nichos/{id}). Custa ~US$ 10 (coletor + fala + IA). Um ramo novo por workspace a cada 30 dias; ramo que já existe devolve o estado dele sem cobrar. `agentes` = ids das SUAS pesquisas (o corpus dá os candidatos) ou `contas` prontas. Sem `confirmarGasto: true` responde 409 com a estimativa.\n\n**Escopo:** `gasto` · **Custo:** ~US$ 10 por ramo · **Limite:** 6 por 60 s\n**Confirmação:** o corpo tem que trazer `\"confirmarGasto\": true` literal.\n**Idempotência:** aceita o header `Idempotency-Key` (repetição em 24 h devolve a mesma resposta).", "security": [ { "chave": [ "gasto" ] } ], "x-escopo": "gasto", "x-classe": "gasto", "x-custo": "~US$ 10 por ramo", "x-confirmacao": "confirmarGasto", "x-idempotencia": true, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Um UUID por operação. Repetir com o mesmo valor em 24 h devolve a resposta gravada, sem cobrar de novo.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "pattern": "^[a-z0-9_]{3,60}$", "description": "Identificador do ramo: minúsculas, dígitos e _ (ex.: usinagem_cnc)" }, "nome": { "type": "string", "minLength": 2, "maxLength": 120, "description": "Nome do ramo como a pessoa diz" }, "agentes": { "description": "Ids das SUAS pesquisas cujo corpus dá os candidatos", "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 } }, "contas": { "description": "Ou os @ do ramo, prontos (40+)", "maxItems": 400, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 60 } }, "confirmarGasto": { "type": "boolean" } }, "required": [ "slug", "nome" ] } } } }, "responses": { "200": { "description": "Ramo já existia", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "criado": { "type": "boolean" }, "estado": { "type": "string" }, "proximoPasso": { "type": "string" } }, "required": [ "id", "criado", "estado", "proximoPasso" ], "additionalProperties": false } } } }, "202": { "description": "Na fila", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "criado": { "type": "boolean" }, "estado": { "type": "string" }, "proximoPasso": { "type": "string" } }, "required": [ "id", "criado", "estado", "proximoPasso" ], "additionalProperties": false } } } }, "400": { "description": "`corpo_invalido` — O JSON não é válido ou não passa na validação do campo (o `detail` diz qual).\n\n`idempotencia_invalida` — O header veio vazio ou com mais de 200 caracteres.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "corpo_invalido": { "$ref": "#/components/examples/corpo_invalido" }, "idempotencia_invalida": { "$ref": "#/components/examples/idempotencia_invalida" } } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "404": { "description": "`nao_encontrado` — O recurso não existe — ou pertence a outro workspace, que responde igual (não revelamos que o id é válido).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "nao_encontrado": { "$ref": "#/components/examples/nao_encontrado" } } } } }, "409": { "description": "`gasto_nao_confirmado` — A rota cobra da conta (fonte ou IA) e o corpo não trouxe `confirmarGasto: true`. O `detail` diz o valor.\n\n`limite_do_plano` — O plano do workspace (Grátis, Pro ou Agência) não comporta mais um deste recurso — nichos, posts, criações, marcas, concorrentes — ou não inclui a ação (publicar no Grátis). O `detail` diz o uso, o limite e o plano que destrava.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "gasto_nao_confirmado": { "$ref": "#/components/examples/gasto_nao_confirmado" }, "limite_do_plano": { "$ref": "#/components/examples/limite_do_plano" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } } } } }, "/api/v1/nichos/{id}": { "get": { "operationId": "nichos.ler", "tags": [ "Ramos" ], "summary": "Um ramo com os jeitos de fazer", "description": "O ramo e os jeitos de fazer de quem está acima do benchmark: 5+ Reels de 3+ contas, quanto renderam na casa de quem postou (× o normal), a abertura mais comum, duração, fala, pedido de ação, preço e 2 exemplos.\n\n**Escopo:** `leitura` · **Custo:** grátis · **Limite:** 120 por 60 s", "security": [ { "chave": [ "leitura" ] } ], "x-escopo": "leitura", "x-classe": "leitura", "x-custo": "grátis", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "O id do recurso, como devolvido pela listagem.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "nome": { "type": "string" }, "estado": { "type": "string", "description": "pedido → ler_bios → aprovar → ler_posts → transcrever → embedar → agrupar → capas → gancho → registrado (ou falhou)" }, "lidoEm": { "type": [ "string", "null" ] }, "contas": { "type": [ "number", "null" ] }, "reels": { "type": [ "number", "null" ] }, "jeitos": { "type": "number" }, "regua": { "anyOf": [ { "type": "object", "properties": { "b1": { "type": "number" }, "r2": { "type": "number" } }, "required": [ "b1", "r2" ], "additionalProperties": false }, { "type": "null" } ] }, "erro": { "type": [ "string", "null" ] }, "atualizadoEm": { "type": "string" }, "meu": { "type": "boolean", "description": "Pedido por este workspace (só então vêm custo e passos)" }, "custoUsd": { "type": [ "number", "null" ] }, "passos": {}, "jeitosDeFazer": { "type": "array", "items": { "type": "object", "properties": { "grupo": { "type": "string" }, "nome": { "type": [ "string", "null" ] }, "explica": { "type": [ "string", "null" ] }, "reels": { "type": "number" }, "contas": { "type": "number" }, "vezesMediana": { "type": "number", "description": "Mediana de views ÷ o normal da casa de quem postou" }, "gancho": { "type": [ "string", "null" ] }, "duracaoS": { "type": [ "number", "null" ] }, "fala": { "type": [ "number", "null" ] }, "pedeAcao": { "type": [ "number", "null" ] }, "dizPreco": { "type": [ "number", "null" ] }, "exemplos": {} }, "required": [ "grupo", "nome", "explica", "reels", "contas", "vezesMediana", "gancho", "duracaoS", "fala", "pedeAcao", "dizPreco", "exemplos" ], "additionalProperties": false } } }, "required": [ "id", "nome", "estado", "lidoEm", "contas", "reels", "jeitos", "regua", "erro", "atualizadoEm", "meu", "jeitosDeFazer" ], "additionalProperties": false } } } }, "400": { "description": "`parametro_invalido` — Um parâmetro de caminho ou de query está fora do formato (id, cursor, data).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "parametro_invalido": { "$ref": "#/components/examples/parametro_invalido" } } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "404": { "description": "`nao_encontrado` — O recurso não existe — ou pertence a outro workspace, que responde igual (não revelamos que o id é válido).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "nao_encontrado": { "$ref": "#/components/examples/nao_encontrado" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } } } } }, "/api/v1/instagram/{handle}": { "get": { "operationId": "instagram.ler", "tags": [ "Instagram" ], "summary": "Uma conta pública do Instagram (leitura guardada)", "description": "A conta como o Pico já leu (até `dias`, padrão 7): perfil, bio, link, contatos escritos na bio (WhatsApp, telefone, e-mail), os últimos posts com legenda, hashtags e imagens, e quanto cada post rendeu contra o normal da PRÓPRIA conta (`vezes`), mais os destaques sem fixados. Para montar landing page, proposta ou diagnóstico de um negócio a partir do perfil dele — o Instagram bloqueia leitura sem login, o Pico já leu. Sem leitura no prazo responde 404 com o próximo passo (`POST /v1/instagram/{handle}/ler`).\n\n**Escopo:** `leitura` · **Custo:** grátis · **Limite:** 120 por 60 s", "security": [ { "chave": [ "leitura" ] } ], "x-escopo": "leitura", "x-classe": "leitura", "x-custo": "grátis", "parameters": [ { "name": "handle", "in": "path", "required": true, "description": "O @ da conta do Instagram (com ou sem @; o link do perfil também serve).", "schema": { "type": "string" } }, { "name": "dias", "in": "query", "required": false, "schema": { "default": 7, "description": "Aceita leitura guardada de até N dias (1–30, padrão 7)", "type": "integer", "minimum": 1, "maximum": 30 }, "description": "Aceita leitura guardada de até N dias (1–30, padrão 7)" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "handle": { "type": "string" }, "rede": { "type": "string", "const": "instagram" }, "url": { "type": "string" }, "lidoEm": { "type": [ "string", "null" ] }, "reaproveitado": { "type": "boolean", "description": "true = não custou nada agora" }, "perfil": { "type": "object", "properties": { "nome": { "type": "string" }, "bio": { "type": "string" }, "site": { "type": "string" }, "categoria": { "type": "string" }, "seguidores": { "type": [ "number", "null" ] }, "seguindo": { "type": [ "number", "null" ] }, "posts": { "type": [ "number", "null" ] }, "verificado": { "type": "boolean" }, "contaComercial": { "type": "boolean" }, "foto": { "type": "string" } }, "required": [ "nome", "bio", "site", "categoria", "seguidores", "seguindo", "posts", "verificado", "contaComercial", "foto" ], "additionalProperties": false }, "contatos": { "type": "object", "properties": { "whatsapp": { "type": "array", "items": { "type": "string" } }, "telefones": { "type": "array", "items": { "type": "string" } }, "emails": { "type": "array", "items": { "type": "string" } }, "links": { "type": "array", "items": { "type": "string" } } }, "required": [ "whatsapp", "telefones", "emails", "links" ], "additionalProperties": false }, "ritmo": { "type": "object", "properties": { "amostra": { "type": "number" }, "postsPorSemana": { "type": [ "number", "null" ] }, "curtidasMediana": { "type": [ "number", "null" ] }, "comentariosMediana": { "type": [ "number", "null" ] }, "viewsMediana": { "type": [ "number", "null" ] }, "formatos": { "type": "object", "properties": { "reel": { "type": "number" }, "carrossel": { "type": "number" }, "imagem": { "type": "number" } }, "required": [ "reel", "carrossel", "imagem" ], "additionalProperties": false } }, "required": [ "amostra", "postsPorSemana", "curtidasMediana", "comentariosMediana", "viewsMediana", "formatos" ], "additionalProperties": false }, "posts": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "tipo": { "type": "string", "enum": [ "reel", "imagem", "carrossel" ] }, "data": { "type": [ "string", "null" ] }, "curtidas": { "type": [ "number", "null" ] }, "comentarios": { "type": [ "number", "null" ] }, "views": { "description": "Plays — só Reel", "type": [ "number", "null" ] }, "vezes": { "description": "Quantas vezes o normal da própria conta (views nos Reels, curtidas nos demais)", "type": [ "number", "null" ] }, "fixado": { "type": "boolean" }, "legenda": { "type": "string" }, "legendaCortada": { "type": "boolean" }, "hashtags": { "type": "array", "items": { "type": "string" } }, "imagens": { "type": "array", "items": { "type": "string" }, "description": "Links do CDN do Instagram — vencem em 2 a 5 dias" } }, "required": [ "url", "tipo", "data", "curtidas", "comentarios", "views", "vezes", "fixado", "legenda", "legendaCortada", "hashtags", "imagens" ], "additionalProperties": false } }, "destaques": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "tipo": { "type": "string", "enum": [ "reel", "imagem", "carrossel" ] }, "vezes": { "type": "number" }, "legenda": { "type": "string" } }, "required": [ "url", "tipo", "vezes", "legenda" ], "additionalProperties": false } }, "avisos": { "type": "array", "items": { "type": "string" } }, "custo": { "type": "object", "properties": { "usd": { "type": "number" } }, "required": [ "usd" ], "additionalProperties": false } }, "required": [ "handle", "rede", "url", "lidoEm", "reaproveitado", "perfil", "contatos", "ritmo", "posts", "destaques", "avisos" ], "additionalProperties": false } } } }, "400": { "description": "`parametro_invalido` — Um parâmetro de caminho ou de query está fora do formato (id, cursor, data).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "parametro_invalido": { "$ref": "#/components/examples/parametro_invalido" } } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "404": { "description": "`nao_encontrado` — O recurso não existe — ou pertence a outro workspace, que responde igual (não revelamos que o id é válido).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "nao_encontrado": { "$ref": "#/components/examples/nao_encontrado" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } } } } }, "/api/v1/instagram/{handle}/ler": { "post": { "operationId": "instagram.lerAgora", "tags": [ "Instagram" ], "summary": "Ler agora uma conta pública do Instagram", "description": "Lê o perfil e os 12 últimos posts agora e devolve o mesmo formato do GET (com `custo`). A conta NÃO vira conta do Monitor nem ocupa a cota do plano. Lida nas últimas 24 h = devolvida sem cobrar. Custa ~US$ 0,003 (o coletor do Pico), dentro do teto do mês. Sem `confirmarGasto: true` responde 409 com a estimativa.\n\n**Escopo:** `gasto` · **Custo:** US$ 0,003 · **Limite:** 6 por 60 s\n**Confirmação:** o corpo tem que trazer `\"confirmarGasto\": true` literal.\n**Idempotência:** aceita o header `Idempotency-Key` (repetição em 24 h devolve a mesma resposta).", "security": [ { "chave": [ "gasto" ] } ], "x-escopo": "gasto", "x-classe": "gasto", "x-custo": "US$ 0,003", "x-confirmacao": "confirmarGasto", "x-idempotencia": true, "parameters": [ { "name": "handle", "in": "path", "required": true, "description": "O @ da conta do Instagram (com ou sem @; o link do perfil também serve).", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Um UUID por operação. Repetir com o mesmo valor em 24 h devolve a resposta gravada, sem cobrar de novo.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmarGasto": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "handle": { "type": "string" }, "rede": { "type": "string", "const": "instagram" }, "url": { "type": "string" }, "lidoEm": { "type": [ "string", "null" ] }, "reaproveitado": { "type": "boolean", "description": "true = não custou nada agora" }, "perfil": { "type": "object", "properties": { "nome": { "type": "string" }, "bio": { "type": "string" }, "site": { "type": "string" }, "categoria": { "type": "string" }, "seguidores": { "type": [ "number", "null" ] }, "seguindo": { "type": [ "number", "null" ] }, "posts": { "type": [ "number", "null" ] }, "verificado": { "type": "boolean" }, "contaComercial": { "type": "boolean" }, "foto": { "type": "string" } }, "required": [ "nome", "bio", "site", "categoria", "seguidores", "seguindo", "posts", "verificado", "contaComercial", "foto" ], "additionalProperties": false }, "contatos": { "type": "object", "properties": { "whatsapp": { "type": "array", "items": { "type": "string" } }, "telefones": { "type": "array", "items": { "type": "string" } }, "emails": { "type": "array", "items": { "type": "string" } }, "links": { "type": "array", "items": { "type": "string" } } }, "required": [ "whatsapp", "telefones", "emails", "links" ], "additionalProperties": false }, "ritmo": { "type": "object", "properties": { "amostra": { "type": "number" }, "postsPorSemana": { "type": [ "number", "null" ] }, "curtidasMediana": { "type": [ "number", "null" ] }, "comentariosMediana": { "type": [ "number", "null" ] }, "viewsMediana": { "type": [ "number", "null" ] }, "formatos": { "type": "object", "properties": { "reel": { "type": "number" }, "carrossel": { "type": "number" }, "imagem": { "type": "number" } }, "required": [ "reel", "carrossel", "imagem" ], "additionalProperties": false } }, "required": [ "amostra", "postsPorSemana", "curtidasMediana", "comentariosMediana", "viewsMediana", "formatos" ], "additionalProperties": false }, "posts": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "tipo": { "type": "string", "enum": [ "reel", "imagem", "carrossel" ] }, "data": { "type": [ "string", "null" ] }, "curtidas": { "type": [ "number", "null" ] }, "comentarios": { "type": [ "number", "null" ] }, "views": { "description": "Plays — só Reel", "type": [ "number", "null" ] }, "vezes": { "description": "Quantas vezes o normal da própria conta (views nos Reels, curtidas nos demais)", "type": [ "number", "null" ] }, "fixado": { "type": "boolean" }, "legenda": { "type": "string" }, "legendaCortada": { "type": "boolean" }, "hashtags": { "type": "array", "items": { "type": "string" } }, "imagens": { "type": "array", "items": { "type": "string" }, "description": "Links do CDN do Instagram — vencem em 2 a 5 dias" } }, "required": [ "url", "tipo", "data", "curtidas", "comentarios", "views", "vezes", "fixado", "legenda", "legendaCortada", "hashtags", "imagens" ], "additionalProperties": false } }, "destaques": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "tipo": { "type": "string", "enum": [ "reel", "imagem", "carrossel" ] }, "vezes": { "type": "number" }, "legenda": { "type": "string" } }, "required": [ "url", "tipo", "vezes", "legenda" ], "additionalProperties": false } }, "avisos": { "type": "array", "items": { "type": "string" } }, "custo": { "type": "object", "properties": { "usd": { "type": "number" } }, "required": [ "usd" ], "additionalProperties": false } }, "required": [ "handle", "rede", "url", "lidoEm", "reaproveitado", "perfil", "contatos", "ritmo", "posts", "destaques", "avisos" ], "additionalProperties": false } } } }, "400": { "description": "`parametro_invalido` — Um parâmetro de caminho ou de query está fora do formato (id, cursor, data).\n\n`corpo_invalido` — O JSON não é válido ou não passa na validação do campo (o `detail` diz qual).\n\n`idempotencia_invalida` — O header veio vazio ou com mais de 200 caracteres.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "parametro_invalido": { "$ref": "#/components/examples/parametro_invalido" }, "corpo_invalido": { "$ref": "#/components/examples/corpo_invalido" }, "idempotencia_invalida": { "$ref": "#/components/examples/idempotencia_invalida" } } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "404": { "description": "`nao_encontrado` — O recurso não existe — ou pertence a outro workspace, que responde igual (não revelamos que o id é válido).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "nao_encontrado": { "$ref": "#/components/examples/nao_encontrado" } } } } }, "409": { "description": "`gasto_nao_confirmado` — A rota cobra da conta (fonte ou IA) e o corpo não trouxe `confirmarGasto: true`. O `detail` diz o valor.\n\n`teto_do_mes` — A chamada estouraria o teto de gasto do mês configurado em Conta → Custo.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "gasto_nao_confirmado": { "$ref": "#/components/examples/gasto_nao_confirmado" }, "teto_do_mes": { "$ref": "#/components/examples/teto_do_mes" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } }, "502": { "description": "`fonte_indisponivel` — A fonte falhou ou a chave dela está ausente/sem saldo.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "fonte_indisponivel": { "$ref": "#/components/examples/fonte_indisponivel" } } } } } } } }, "/api/v1/carrosseis": { "get": { "operationId": "carrosseis.listar", "tags": [ "Carrosséis" ], "summary": "Carrosséis que viralizaram nas contas do nicho", "description": "Da leitura que o Pico já fez das contas do nicho de uma pesquisa (últimos 30 dias): os carrosséis com pelo menos 2 vezes as curtidas normais da própria conta — comparados com os outros carrosséis dela (3+) ou com todos os posts (5+); sem fixados nem os postados nos últimos 7 dias; no máximo 3 por conta. Traz a legenda, as hashtags, quantas telas e os links das imagens (vencem em dias). Grátis: não lê nada novo.\n\n**Escopo:** `leitura` · **Custo:** grátis · **Limite:** 120 por 60 s", "security": [ { "chave": [ "leitura" ] } ], "x-escopo": "leitura", "x-classe": "leitura", "x-custo": "grátis", "parameters": [ { "name": "pesquisa", "in": "query", "required": false, "schema": { "description": "O id da pesquisa (pico_pesquisa_listar). Sem ele, a mais recente com coleta.", "type": "string", "minLength": 1, "maxLength": 120 }, "description": "O id da pesquisa (pico_pesquisa_listar). Sem ele, a mais recente com coleta." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "agente": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "nome": { "type": "string" } }, "required": [ "id", "nome" ], "additionalProperties": false }, { "type": "null" } ] }, "contasDoNicho": { "type": "number", "description": "Contas do nicho na coleta da pesquisa" }, "contasLidas": { "type": "number", "description": "Delas, quantas o Pico leu nos últimos 30 dias (a base da lista)" }, "itens": { "type": "array", "items": { "type": "object", "properties": { "conta": { "type": "string" }, "seguidores": { "type": [ "number", "null" ] }, "url": { "type": "string" }, "shortcode": { "type": [ "string", "null" ] }, "data": { "type": [ "string", "null" ] }, "curtidas": { "type": "number" }, "comentarios": { "type": [ "number", "null" ] }, "vezes": { "type": "number", "description": "Curtidas ÷ o normal da própria conta (2 ou mais)" }, "base": { "type": "string", "enum": [ "carrosseis", "posts" ], "description": "Com o que se comparou: os outros carrosséis da conta, ou todos os posts dela" }, "normal": { "type": "number" }, "telas": { "type": "number" }, "legenda": { "type": "string" }, "hashtags": { "type": "array", "items": { "type": "string" } }, "imagens": { "type": "array", "items": { "type": "string" }, "description": "Links do CDN do Instagram — vencem em 2 a 5 dias" }, "doRamo": { "description": "A ficha da pesquisa reconhece o assunto (true) — esses vêm primeiro; null = sem sinal. Os de assunto fora do ramo não entram.", "type": [ "boolean", "null" ] } }, "required": [ "conta", "seguidores", "url", "shortcode", "data", "curtidas", "comentarios", "vezes", "base", "normal", "telas", "legenda", "hashtags", "imagens", "doRamo" ], "additionalProperties": false } } }, "required": [ "agente", "contasDoNicho", "contasLidas", "itens" ], "additionalProperties": false } } } }, "400": { "description": "`parametro_invalido` — Um parâmetro de caminho ou de query está fora do formato (id, cursor, data).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "parametro_invalido": { "$ref": "#/components/examples/parametro_invalido" } } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "404": { "description": "`nao_encontrado` — O recurso não existe — ou pertence a outro workspace, que responde igual (não revelamos que o id é válido).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "nao_encontrado": { "$ref": "#/components/examples/nao_encontrado" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } } } } }, "/api/v1/pecas": { "get": { "operationId": "pecas.listar", "tags": [ "Peças" ], "summary": "Listar peças", "description": "Rascunhos (o que a IA gerou; `origem: rascunho`) e compromissos no calendário (`origem: calendario`, com status e métricas). `?estado=` filtra.\n\n**Escopo:** `leitura` · **Custo:** grátis · **Limite:** 120 por 60 s", "security": [ { "chave": [ "leitura" ] } ], "x-escopo": "leitura", "x-classe": "leitura", "x-custo": "grátis", "parameters": [ { "name": "estado", "in": "query", "required": false, "schema": { "default": "todas", "type": "string", "enum": [ "rascunho", "agendada", "publicada", "todas" ] } }, { "name": "clientId", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "itens": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "origem": { "type": "string", "const": "rascunho" }, "id": { "type": "string" }, "title": { "type": "string" }, "kind": { "type": "string", "enum": [ "script", "brief", "hooks", "carousel", "legenda" ] }, "sourceLabel": { "type": "string" }, "body": { "type": "string", "description": "Roteiro/brief/ganchos/legenda em texto; carrossel em JSON {slides:[{titulo,texto}]}" }, "createdAt": { "type": "string", "description": "Instante em ISO-8601 UTC, ex. 2026-09-11T12:00:00.000Z" }, "provenance": { "type": "object", "properties": { "hookText": { "type": "string" }, "creatorHandle": { "type": "string" }, "creatorPlatform": { "type": "string", "enum": [ "instagram", "tiktok", "youtube" ] }, "outlierRatio": { "type": "number" }, "sourceVideoId": { "type": "string" }, "nicheId": { "type": "string" }, "nicheLabel": { "type": "string" } }, "required": [ "hookText" ], "additionalProperties": false } }, "required": [ "origem", "id", "title", "kind", "sourceLabel", "body", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "origem": { "type": "string", "const": "calendario" }, "id": { "type": "string" }, "clientId": { "type": "string" }, "title": { "type": "string" }, "kind": { "type": "string", "enum": [ "reel", "carousel", "story", "post" ] }, "status": { "type": "string", "enum": [ "local_draft", "ready", "publishing", "published", "failed", "cancelled" ] }, "body": { "type": "string" }, "caption": { "type": "string" }, "scheduledAt": { "type": "string", "description": "Instante em ISO-8601 UTC, ex. 2026-09-11T12:00:00.000Z" }, "publishedAt": { "type": "string", "description": "Instante em ISO-8601 UTC, ex. 2026-09-11T12:00:00.000Z" }, "network": { "type": "string", "enum": [ "instagram", "tiktok", "youtube" ] }, "provenance": { "type": "object", "properties": { "hookText": { "type": "string" }, "creatorHandle": { "type": "string" }, "creatorPlatform": { "type": "string", "enum": [ "instagram", "tiktok", "youtube" ] }, "outlierRatio": { "type": "number" }, "sourceVideoId": { "type": "string" }, "nicheId": { "type": "string" }, "nicheLabel": { "type": "string" } }, "required": [ "hookText" ], "additionalProperties": false }, "metrics": { "type": "object", "properties": { "likes": { "type": "number" }, "comments": { "type": "number" }, "shares": { "type": "number" }, "saves": { "type": "number" }, "views": { "type": "number" } }, "required": [ "likes", "comments", "shares" ], "additionalProperties": false } }, "required": [ "origem", "id", "clientId", "title", "kind", "status", "body", "caption", "network" ], "additionalProperties": false } ] } } }, "required": [ "itens" ], "additionalProperties": false } } } }, "400": { "description": "`parametro_invalido` — Um parâmetro de caminho ou de query está fora do formato (id, cursor, data).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "parametro_invalido": { "$ref": "#/components/examples/parametro_invalido" } } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } } } }, "post": { "operationId": "pecas.criar", "tags": [ "Peças" ], "summary": "Criar uma peça com IA", "description": "Roteiro de 30 s, brief, 12 ganchos, carrossel (JSON de lâminas) ou legenda (o texto para colar no post). O perfil do negócio (tom, CTA, o que não fazer) entra sozinho. Grava como rascunho. IA do Pico.\n\n**Escopo:** `gasto` · **Custo:** IA do Pico · **Limite:** 6 por 60 s\n**Idempotência:** aceita o header `Idempotency-Key` (repetição em 24 h devolve a mesma resposta).", "security": [ { "chave": [ "gasto" ] } ], "x-escopo": "gasto", "x-classe": "gasto", "x-custo": "IA do Pico", "x-idempotencia": true, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Um UUID por operação. Repetir com o mesmo valor em 24 h devolve a resposta gravada, sem cobrar de novo.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CriarPecaEntrada" } } } }, "responses": { "201": { "description": "Rascunho criado", "content": { "application/json": { "schema": { "type": "object", "properties": { "origem": { "type": "string", "const": "rascunho" }, "id": { "type": "string" }, "title": { "type": "string" }, "kind": { "type": "string", "enum": [ "script", "brief", "hooks", "carousel", "legenda" ] }, "sourceLabel": { "type": "string" }, "body": { "type": "string", "description": "Roteiro/brief/ganchos/legenda em texto; carrossel em JSON {slides:[{titulo,texto}]}" }, "createdAt": { "type": "string", "description": "Instante em ISO-8601 UTC, ex. 2026-09-11T12:00:00.000Z" }, "provenance": { "type": "object", "properties": { "hookText": { "type": "string" }, "creatorHandle": { "type": "string" }, "creatorPlatform": { "type": "string", "enum": [ "instagram", "tiktok", "youtube" ] }, "outlierRatio": { "type": "number" }, "sourceVideoId": { "type": "string" }, "nicheId": { "type": "string" }, "nicheLabel": { "type": "string" } }, "required": [ "hookText" ], "additionalProperties": false }, "custo": { "type": "object", "properties": { "usd": { "type": "number", "description": "O valor cobrado nesta chamada, em dólares" }, "fonte": { "type": "string", "enum": [ "x-cost", "cache", "ia-do-pico" ], "description": "x-cost = header real da fonte; cache = a fonte não cobrou; ia-do-pico = IA paga pelo Pico, não pela sua conta" } }, "required": [ "usd", "fonte" ], "additionalProperties": false } }, "required": [ "origem", "id", "title", "kind", "sourceLabel", "body", "createdAt", "custo" ], "additionalProperties": false } } } }, "400": { "description": "`corpo_invalido` — O JSON não é válido ou não passa na validação do campo (o `detail` diz qual).\n\n`idempotencia_invalida` — O header veio vazio ou com mais de 200 caracteres.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "corpo_invalido": { "$ref": "#/components/examples/corpo_invalido" }, "idempotencia_invalida": { "$ref": "#/components/examples/idempotencia_invalida" } } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } }, "502": { "description": "`ia_indisponivel` — O provedor de IA falhou ou está sem crédito.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "ia_indisponivel": { "$ref": "#/components/examples/ia_indisponivel" } } } } } } } }, "/api/v1/pecas/{id}": { "get": { "operationId": "pecas.ler", "tags": [ "Peças" ], "summary": "Uma peça", "description": "Rascunho ou compromisso (com métricas quando publicada). De outro workspace = 404.\n\n**Escopo:** `leitura` · **Custo:** grátis · **Limite:** 120 por 60 s", "security": [ { "chave": [ "leitura" ] } ], "x-escopo": "leitura", "x-classe": "leitura", "x-custo": "grátis", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "O id do recurso, como devolvido pela listagem.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Peca" } } } }, "400": { "description": "`parametro_invalido` — Um parâmetro de caminho ou de query está fora do formato (id, cursor, data).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "parametro_invalido": { "$ref": "#/components/examples/parametro_invalido" } } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "404": { "description": "`peca_desconhecida` — A peça não existe ou é de outro workspace.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "peca_desconhecida": { "$ref": "#/components/examples/peca_desconhecida" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } } } }, "put": { "operationId": "pecas.editar", "tags": [ "Peças" ], "summary": "Editar um rascunho", "description": "Título e/ou corpo. Compromisso no calendário não se edita por aqui — cancele e crie outro.\n\n**Escopo:** `escrita` · **Custo:** grátis · **Limite:** 30 por 60 s", "security": [ { "chave": [ "escrita" ] } ], "x-escopo": "escrita", "x-classe": "escrita", "x-custo": "grátis", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "O id do recurso, como devolvido pela listagem.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditarPecaEntrada" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Rascunho" } } } }, "400": { "description": "`corpo_invalido` — O JSON não é válido ou não passa na validação do campo (o `detail` diz qual).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "corpo_invalido": { "$ref": "#/components/examples/corpo_invalido" } } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "404": { "description": "`peca_desconhecida` — A peça não existe ou é de outro workspace.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "peca_desconhecida": { "$ref": "#/components/examples/peca_desconhecida" } } } } }, "409": { "description": "`peca_nao_e_rascunho` — Editar só vale para rascunho; a peça já é compromisso no calendário.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "peca_nao_e_rascunho": { "$ref": "#/components/examples/peca_nao_e_rascunho" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } } } }, "delete": { "operationId": "pecas.apagar", "tags": [ "Peças" ], "summary": "Apagar rascunho ou cancelar compromisso", "description": "Rascunho some. Compromisso `pendente` vira `cancelado`. Publicada não se cancela.\n\n**Escopo:** `escrita` · **Custo:** grátis · **Limite:** 30 por 60 s", "security": [ { "chave": [ "escrita" ] } ], "x-escopo": "escrita", "x-classe": "escrita", "x-custo": "grátis", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "O id do recurso, como devolvido pela listagem.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Apagada/cancelada" }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "404": { "description": "`peca_desconhecida` — A peça não existe ou é de outro workspace.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "peca_desconhecida": { "$ref": "#/components/examples/peca_desconhecida" } } } } }, "409": { "description": "`peca_nao_e_rascunho` — Editar só vale para rascunho; a peça já é compromisso no calendário.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "peca_nao_e_rascunho": { "$ref": "#/components/examples/peca_nao_e_rascunho" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } } } } }, "/api/v1/pecas/{id}/agendar": { "post": { "operationId": "pecas.agendar", "tags": [ "Peças" ], "summary": "Agendar um rascunho", "description": "Vira compromisso no calendário (`post`), sem publicar. Brief e lista de ganchos não vão para o calendário. `clientId` escolhe o workspace (conferido).\n\n**Escopo:** `escrita` · **Custo:** grátis · **Limite:** 30 por 60 s", "security": [ { "chave": [ "escrita" ] } ], "x-escopo": "escrita", "x-classe": "escrita", "x-custo": "grátis", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "O id do recurso, como devolvido pela listagem.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgendarPecaEntrada" } } } }, "responses": { "201": { "description": "Agendada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agendada" } } } }, "400": { "description": "`corpo_invalido` — O JSON não é válido ou não passa na validação do campo (o `detail` diz qual).\n\n`kind_nao_publica` — Brief e lista de ganchos não vão para o calendário.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "corpo_invalido": { "$ref": "#/components/examples/corpo_invalido" }, "kind_nao_publica": { "$ref": "#/components/examples/kind_nao_publica" } } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "404": { "description": "`peca_desconhecida` — A peça não existe ou é de outro workspace.\n\n`nao_encontrado` — O recurso não existe — ou pertence a outro workspace, que responde igual (não revelamos que o id é válido).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "peca_desconhecida": { "$ref": "#/components/examples/peca_desconhecida" }, "nao_encontrado": { "$ref": "#/components/examples/nao_encontrado" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } } } } }, "/api/v1/pecas/{id}/publicar": { "post": { "operationId": "pecas.publicar", "tags": [ "Peças" ], "summary": "Publicar agora", "description": "Sai pela ponte, síncrono, na sua conta da rede. A rede não guarda rascunho e não dá para desfazer — por isso exige `confirmar: true` literal e o escopo `publicacao`. Precisa de mídia acessível (`sem_midia` explica).\n\n**Escopo:** `publicacao` · **Custo:** grátis (1 publicação da cota da rede) · **Limite:** 6 por 60 s\n**Confirmação:** o corpo tem que trazer `\"confirmar\": true` literal.", "security": [ { "chave": [ "publicacao" ] } ], "x-escopo": "publicacao", "x-classe": "publicacao", "x-custo": "grátis (1 publicação da cota da rede)", "x-confirmacao": "confirmar", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "O id do recurso, como devolvido pela listagem.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicarEntrada" } } } }, "responses": { "200": { "description": "Publicada (ou já estava)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Publicada" } } } }, "400": { "description": "`confirmacao_ausente` — Publicar e responder agem na conta de um terceiro e exigem `confirmar: true` literal no corpo.\n\n`corpo_invalido` — O JSON não é válido ou não passa na validação do campo (o `detail` diz qual).\n\n`recusado` — O motor de publicação recusou antes de tocar a rede (falta de confirmação explícita ou peça inválida). O `detail` diz o motivo.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "confirmacao_ausente": { "$ref": "#/components/examples/confirmacao_ausente" }, "corpo_invalido": { "$ref": "#/components/examples/corpo_invalido" }, "recusado": { "$ref": "#/components/examples/recusado" } } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "404": { "description": "`peca_desconhecida` — A peça não existe ou é de outro workspace.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "peca_desconhecida": { "$ref": "#/components/examples/peca_desconhecida" } } } } }, "409": { "description": "`ponte_nao_configurada` — A chave da ponte de publicação não está no ambiente.\n\n`em_andamento` — A peça já está sendo publicada por outra chamada.\n\n`sem_conta` — O workspace não tem conta da rede conectada e ativa.\n\n`sem_midia` — A peça não tem imagem/vídeo acessível pelo servidor; a rede não aceita post sem mídia.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "ponte_nao_configurada": { "$ref": "#/components/examples/ponte_nao_configurada" }, "em_andamento": { "$ref": "#/components/examples/em_andamento" }, "sem_conta": { "$ref": "#/components/examples/sem_conta" }, "sem_midia": { "$ref": "#/components/examples/sem_midia" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.\n\n`adiado` — O teto de publicações/interações da conta na rede foi atingido; o cron tenta depois.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" }, "adiado": { "$ref": "#/components/examples/adiado" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } }, "502": { "description": "`falhou` — A rede/ponte respondeu erro. O `detail` traz o motivo e o `requestId` para o suporte.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "falhou": { "$ref": "#/components/examples/falhou" } } } } } } } }, "/api/v1/leads": { "get": { "operationId": "leads.listar", "tags": [ "Leads" ], "summary": "Listar leads", "description": "Comentários e DMs que pedem resposta, com a janela (7 d para private reply, 24 h para DM) e o status.\n\n**Escopo:** `leitura` · **Custo:** grátis · **Limite:** 120 por 60 s", "security": [ { "chave": [ "leitura" ] } ], "x-escopo": "leitura", "x-classe": "leitura", "x-custo": "grátis", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "open", "replied", "lost_window", "converted" ] } }, { "name": "clientId", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "itens": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "clientId": { "type": "string" }, "network": { "type": "string", "enum": [ "instagram", "tiktok", "youtube" ] }, "channel": { "type": "string", "enum": [ "comment", "dm" ] }, "fromHandle": { "type": "string" }, "excerpt": { "type": "string" }, "createdAt": { "type": "string", "description": "Instante em ISO-8601 UTC, ex. 2026-09-11T12:00:00.000Z" }, "windowEndsAt": { "description": "Fim da janela: private reply 7 d, DM 24 h", "type": "string" }, "status": { "type": "string", "enum": [ "open", "replied", "lost_window", "converted" ] }, "privateReplyUsed": { "type": "boolean" }, "public": { "type": "boolean", "description": "true = a resposta será um comentário PÚBLICO" }, "manualReplyAt": { "type": "string", "description": "Instante em ISO-8601 UTC, ex. 2026-09-11T12:00:00.000Z" } }, "required": [ "id", "clientId", "network", "channel", "fromHandle", "excerpt", "createdAt", "status", "privateReplyUsed", "public" ], "additionalProperties": false } } }, "required": [ "itens" ], "additionalProperties": false } } } }, "400": { "description": "`parametro_invalido` — Um parâmetro de caminho ou de query está fora do formato (id, cursor, data).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "parametro_invalido": { "$ref": "#/components/examples/parametro_invalido" } } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } } } } }, "/api/v1/leads/{id}/responder": { "post": { "operationId": "leads.responder", "tags": [ "Leads" ], "summary": "Responder um lead", "description": "Comentário PÚBLICO no post ou DM na conversa, em nome da conta. Gasta 1 interação da cota. Exige `confirmar: true` e o escopo `publicacao`. `public` no lead diz qual dos dois.\n\n**Escopo:** `publicacao` · **Custo:** 1 interação da cota da rede · **Limite:** 6 por 60 s\n**Confirmação:** o corpo tem que trazer `\"confirmar\": true` literal.", "security": [ { "chave": [ "publicacao" ] } ], "x-escopo": "publicacao", "x-classe": "publicacao", "x-custo": "1 interação da cota da rede", "x-confirmacao": "confirmar", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "O id do recurso, como devolvido pela listagem.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponderEntrada" } } } }, "responses": { "200": { "description": "Enviada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Respondida" } } } }, "400": { "description": "`confirmacao_ausente` — Publicar e responder agem na conta de um terceiro e exigem `confirmar: true` literal no corpo.\n\n`corpo_invalido` — O JSON não é válido ou não passa na validação do campo (o `detail` diz qual).\n\n`canal_invalido` — O lead não é de comentário nem de DM respondível.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "confirmacao_ausente": { "$ref": "#/components/examples/confirmacao_ausente" }, "corpo_invalido": { "$ref": "#/components/examples/corpo_invalido" }, "canal_invalido": { "$ref": "#/components/examples/canal_invalido" } } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "404": { "description": "`nao_encontrado` — O recurso não existe — ou pertence a outro workspace, que responde igual (não revelamos que o id é válido).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "nao_encontrado": { "$ref": "#/components/examples/nao_encontrado" } } } } }, "409": { "description": "`ja_respondido` — Este lead já recebeu resposta (a rede permite 1 private reply por comentário).\n\n`janela_fechada` — Passaram 7 dias do comentário (private reply) ou 24 h da última DM: a rede não aceita mais resposta.\n\n`sem_conta` — O workspace não tem conta da rede conectada e ativa.\n\n`sem_post` — O comentário é de um post que o Pico não conhece.\n\n`sem_conversa` — A DM não tem conversa aberta na ponte.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "ja_respondido": { "$ref": "#/components/examples/ja_respondido" }, "janela_fechada": { "$ref": "#/components/examples/janela_fechada" }, "sem_conta": { "$ref": "#/components/examples/sem_conta" }, "sem_post": { "$ref": "#/components/examples/sem_post" }, "sem_conversa": { "$ref": "#/components/examples/sem_conversa" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.\n\n`adiado` — O teto de publicações/interações da conta na rede foi atingido; o cron tenta depois.\n\n`cota_esgotada` — A conta gastou as interações do período na rede.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" }, "adiado": { "$ref": "#/components/examples/adiado" }, "cota_esgotada": { "$ref": "#/components/examples/cota_esgotada" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } }, "502": { "description": "`falhou` — A rede/ponte respondeu erro. O `detail` traz o motivo e o `requestId` para o suporte.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "falhou": { "$ref": "#/components/examples/falhou" } } } } } } } }, "/api/v1/inbox": { "get": { "operationId": "inbox.ler", "tags": [ "Leads" ], "summary": "Inbox da ponte", "description": "Mensagens, comentários ou avaliações — só das contas do seu workspace. `?conversa=` abre uma conversa. Só leitura.\n\n**Escopo:** `leitura` · **Custo:** grátis · **Limite:** 120 por 60 s", "security": [ { "chave": [ "leitura" ] } ], "x-escopo": "leitura", "x-classe": "leitura", "x-custo": "grátis", "parameters": [ { "name": "aba", "in": "query", "required": false, "schema": { "default": "mensagens", "type": "string", "enum": [ "mensagens", "comentarios", "avaliacoes" ] } }, { "name": "conversa", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Inbox" } } } }, "400": { "description": "`parametro_invalido` — Um parâmetro de caminho ou de query está fora do formato (id, cursor, data).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "parametro_invalido": { "$ref": "#/components/examples/parametro_invalido" } } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "404": { "description": "`nao_encontrado` — O recurso não existe — ou pertence a outro workspace, que responde igual (não revelamos que o id é válido).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "nao_encontrado": { "$ref": "#/components/examples/nao_encontrado" } } } } }, "409": { "description": "`ponte_nao_configurada` — A chave da ponte de publicação não está no ambiente.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "ponte_nao_configurada": { "$ref": "#/components/examples/ponte_nao_configurada" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } }, "502": { "description": "`falhou` — A rede/ponte respondeu erro. O `detail` traz o motivo e o `requestId` para o suporte.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "falhou": { "$ref": "#/components/examples/falhou" } } } } } } } }, "/api/v1/resultado": { "get": { "operationId": "resultado.ler", "tags": [ "Peças" ], "summary": "Resultado das publicadas", "description": "Só peças publicadas, com métricas, no período. Totais somados.\n\n**Escopo:** `leitura` · **Custo:** grátis · **Limite:** 120 por 60 s", "security": [ { "chave": [ "leitura" ] } ], "x-escopo": "leitura", "x-classe": "leitura", "x-custo": "grátis", "parameters": [ { "name": "de", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "ate", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "clientId", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resultado" } } } }, "400": { "description": "`parametro_invalido` — Um parâmetro de caminho ou de query está fora do formato (id, cursor, data).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "parametro_invalido": { "$ref": "#/components/examples/parametro_invalido" } } } } }, "401": { "description": "`chave_invalida` — A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito.\n\n`sem_sessao` — A rota aceita só sessão do app (cookie) e a request veio sem ela.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "chave_invalida": { "$ref": "#/components/examples/chave_invalida" }, "sem_sessao": { "$ref": "#/components/examples/sem_sessao" } } } }, "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer realm=\"pico\"" } } }, "403": { "description": "`escopo_insuficiente` — A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "escopo_insuficiente": { "$ref": "#/components/examples/escopo_insuficiente" } } } } }, "429": { "description": "`limite_excedido` — A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "limite_excedido": { "$ref": "#/components/examples/limite_excedido" } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até a janela virar" } } }, "500": { "description": "`erro_interno` — Algo quebrou do nosso lado. O detalhe foi para o log, não para cá.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problema" }, "examples": { "erro_interno": { "$ref": "#/components/examples/erro_interno" } } } } } } } } }, "components": { "securitySchemes": { "chave": { "type": "http", "scheme": "bearer", "bearerFormat": "pico_sk_…", "description": "A chave de API criada em Conta → API e MCP." }, "sessao": { "type": "apiKey", "in": "cookie", "name": "__Host-grok-auth.session_token", "description": "A sessão do app (só as rotas de gestão de chave)." } }, "schemas": { "Saude": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "versao": { "type": "string" }, "hora": { "type": "string", "description": "Instante em ISO-8601 UTC, ex. 2026-09-11T12:00:00.000Z" } }, "required": [ "ok", "versao", "hora" ], "additionalProperties": false }, "Eu": { "type": "object", "properties": { "tenant": { "type": "object", "properties": { "id": { "type": "string" }, "nome": { "type": [ "string", "null" ] }, "modo": { "anyOf": [ { "type": "string", "enum": [ "direto", "agencia" ] }, { "type": "null" } ] } }, "required": [ "id", "nome", "modo" ], "additionalProperties": false }, "operador": { "type": "object", "properties": { "id": { "type": "string" }, "nome": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "nome", "email" ], "additionalProperties": false }, "via": { "type": "string", "enum": [ "chave", "sessao" ] }, "chaveId": { "type": [ "string", "null" ] }, "chave": { "anyOf": [ { "type": "object", "properties": { "nome": { "type": "string" }, "expiraEm": { "anyOf": [ { "type": "string", "description": "Instante em ISO-8601 UTC, ex. 2026-09-11T12:00:00.000Z" }, { "type": "null" } ] } }, "required": [ "nome", "expiraEm" ], "additionalProperties": false }, { "type": "null" } ], "description": "Só via chave: nome e validade (null = sem prazo)" }, "escopos": { "type": "array", "items": { "type": "string", "enum": [ "leitura", "escrita", "gasto", "publicacao" ] } }, "escoposDisponiveis": { "type": "array", "items": { "type": "object", "properties": { "escopo": { "type": "string", "enum": [ "leitura", "escrita", "gasto", "publicacao" ] }, "descricao": { "type": "string" } }, "required": [ "escopo", "descricao" ], "additionalProperties": false } }, "limites": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "janelaS": { "type": "number" }, "max": { "type": "number" } }, "required": [ "janelaS", "max" ], "additionalProperties": false } }, "versao": { "type": "string" } }, "required": [ "tenant", "operador", "via", "chaveId", "chave", "escopos", "escoposDisponiveis", "limites", "versao" ], "additionalProperties": false }, "Problema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "enum": [ "chave_invalida", "sem_sessao", "so_sessao", "escopo_insuficiente", "cross_site", "corpo_invalido", "parametro_invalido", "metodo_nao_permitido", "nao_encontrado", "confirmacao_ausente", "gasto_nao_confirmado", "teto_do_mes", "limite_do_plano", "limite_excedido", "idempotencia_invalida", "recusado", "peca_desconhecida", "peca_nao_e_rascunho", "sem_midia", "sem_conta", "ponte_nao_configurada", "em_andamento", "ja_publicado", "adiado", "falhou", "cota_esgotada", "janela_fechada", "ja_respondido", "canal_invalido", "sem_post", "sem_conversa", "pesquisa_em_andamento", "kind_nao_publica", "conexao_recusada", "termo_pendente", "rede_invalida", "ia_indisponivel", "fonte_indisponivel", "erro_interno" ] }, "detail": { "type": "string" }, "instance": { "type": "string" } }, "required": [ "type", "title", "status", "code" ], "additionalProperties": {} }, "CriarChaveEntrada": { "type": "object", "properties": { "nome": { "type": "string", "minLength": 1, "maxLength": 80 }, "escopos": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "leitura", "escrita", "gasto", "publicacao" ] } }, "validadeDias": { "anyOf": [ { "anyOf": [ { "type": "number", "const": 30 }, { "type": "number", "const": 90 } ] }, { "type": "null" } ] } }, "required": [ "nome", "escopos" ] }, "ChaveCriada": { "type": "object", "properties": { "id": { "type": "string" }, "nome": { "type": "string" }, "prefixo": { "type": "string", "description": "pico_sk_ + 6 caracteres — o que a lista mostra" }, "escopos": { "type": "array", "items": { "type": "string", "enum": [ "leitura", "escrita", "gasto", "publicacao" ] } }, "criadaEm": { "type": "string", "description": "Instante em ISO-8601 UTC, ex. 2026-09-11T12:00:00.000Z" }, "expiraEm": { "anyOf": [ { "type": "string", "description": "Instante em ISO-8601 UTC, ex. 2026-09-11T12:00:00.000Z" }, { "type": "null" } ] }, "ultimoUsoEm": { "anyOf": [ { "type": "string", "description": "Instante em ISO-8601 UTC, ex. 2026-09-11T12:00:00.000Z" }, { "type": "null" } ] }, "revogadaEm": { "anyOf": [ { "type": "string", "description": "Instante em ISO-8601 UTC, ex. 2026-09-11T12:00:00.000Z" }, { "type": "null" } ] }, "chave": { "type": "string", "description": "A chave inteira. Aparece SÓ nesta resposta; guarde agora." } }, "required": [ "id", "nome", "prefixo", "escopos", "criadaEm", "expiraEm", "ultimoUsoEm", "revogadaEm", "chave" ], "additionalProperties": false }, "PerfilInput": { "type": "object", "properties": { "nome": { "type": "string", "maxLength": 120 }, "segmento": { "type": "string", "maxLength": 120 }, "descricao": { "default": "", "type": "string", "maxLength": 600 }, "publico": { "default": "", "type": "string", "maxLength": 300 }, "objetivo": { "type": "string", "enum": [ "lead", "venda", "marca" ] }, "regiao": { "default": "", "type": "string", "maxLength": 120 }, "idioma": { "default": "pt-BR", "type": "string", "maxLength": 10 }, "cta": { "default": "", "type": "string", "maxLength": 300 }, "palavraChave": { "default": "", "type": "string", "maxLength": 60 }, "perfil": { "type": "object", "properties": { "produtos": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 } }, "tom": { "type": "object", "properties": { "descricao": { "default": "", "type": "string", "maxLength": 400 }, "exemplos": { "maxItems": 5, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } }, "evitar": { "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 } } } }, "pilares": { "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 } }, "referencias": { "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "handle": { "type": "string" }, "platform": { "type": "string", "enum": [ "tiktok", "youtube", "instagram" ] } }, "required": [ "handle", "platform" ] } }, "evitarPalavras": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 } }, "plataformas": { "default": [], "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "tiktok", "youtube", "instagram" ] } }, "hashtags": { "maxItems": 15, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 60 } }, "links": { "default": { "site": "", "whatsapp": "" }, "type": "object", "properties": { "site": { "default": "", "type": "string", "maxLength": 300 }, "whatsapp": { "default": "", "type": "string", "maxLength": 60 } } }, "oferta": { "default": "", "type": "string", "maxLength": 400 }, "ancora": { "default": "", "type": "string", "maxLength": 200 }, "contextoLivre": { "default": "", "type": "string", "maxLength": 3000 }, "atendimento": { "default": "", "anyOf": [ { "type": "string", "enum": [ "local", "distancia" ] }, { "type": "string", "const": "" } ] }, "sugeridosPelaIa": { "type": "array", "items": { "type": "string", "enum": [ "descricao", "publico", "regiao", "produtos", "pilares", "tom", "oferta", "segmento" ] } } } } }, "required": [ "nome", "segmento", "objetivo" ] }, "CustoDoMes": { "type": "object", "properties": { "clientId": { "type": "string" }, "month": { "type": "string", "description": "AAAA-MM" }, "researchUsd": { "type": "number" }, "retainerBrl": { "type": [ "number", "null" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "string", "description": "Instante em ISO-8601 UTC, ex. 2026-09-11T12:00:00.000Z" }, "label": { "type": "string" }, "usd": { "type": "number" }, "clientId": { "type": "string" }, "fontePath": { "type": "string" }, "attributed": { "type": "boolean" } }, "required": [ "at", "label", "usd", "clientId", "attributed" ], "additionalProperties": false } }, "teto": { "type": "object", "properties": { "usdMes": { "description": "null = sem teto", "type": [ "number", "null" ] }, "gastoNoMesUsd": { "type": "number" } }, "required": [ "usdMes", "gastoNoMesUsd" ], "additionalProperties": false } }, "required": [ "clientId", "month", "researchUsd", "retainerBrl", "lines", "teto" ], "additionalProperties": false }, "TetoEntrada": { "type": "object", "properties": { "usdMes": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 10000 }, { "type": "null" } ] } }, "required": [ "usdMes" ] }, "Conexoes": { "type": "object", "properties": { "clientId": { "type": "string" }, "handle": { "type": "string" }, "redes": { "type": "array", "items": { "type": "object", "properties": { "network": { "type": "string", "enum": [ "instagram", "tiktok", "youtube" ] }, "connected": { "type": "boolean" }, "status": { "type": "string", "enum": [ "alive", "expiring", "dead", "missing" ] }, "tokenExpiresAt": { "type": "string", "description": "Instante em ISO-8601 UTC, ex. 2026-09-11T12:00:00.000Z" }, "canPublish": { "type": "boolean" }, "canReadComments": { "type": "boolean" }, "canStartDm": { "type": "boolean" }, "canPrivateReply": { "type": "boolean" }, "dmAllowsLinks": { "type": "boolean" }, "handle": { "type": "string" }, "viaSocialApi": { "type": "boolean" } }, "required": [ "network", "connected", "status", "canPublish", "canReadComments", "canStartDm", "canPrivateReply", "dmAllowsLinks" ], "additionalProperties": false } } }, "required": [ "clientId", "handle", "redes" ], "additionalProperties": false }, "Conexao": { "type": "object", "properties": { "rede": { "type": "string", "enum": [ "instagram", "tiktok", "youtube" ] }, "url": { "type": "string", "format": "uri" }, "comoUsar": { "type": "string" } }, "required": [ "rede", "url", "comoUsar" ], "additionalProperties": false }, "CriarPesquisaEntrada": { "type": "object", "properties": { "nome": { "type": "string", "maxLength": 200 }, "intent": { "type": "string", "minLength": 1, "maxLength": 2000 }, "keywords": { "minItems": 1, "maxItems": 30, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 } }, "excludeKeywords": { "maxItems": 30, "type": "array", "items": { "type": "string", "maxLength": 120 } }, "platforms": { "minItems": 1, "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "tiktok", "youtube", "instagram" ] } }, "dataIntelligence": { "default": false, "type": "boolean" }, "metaAds": { "default": false, "type": "boolean" }, "recorrente": { "default": false, "type": "boolean" }, "cadencia": { "type": "string", "enum": [ "daily", "weekly", "monthly" ] }, "englishOnly": { "type": "boolean" }, "confirmarGasto": { "type": "boolean" } }, "required": [ "intent", "keywords", "platforms" ] }, "PesquisaCriada": { "type": "object", "properties": { "id": { "type": "string" }, "nome": { "type": "string" }, "intent": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" } }, "excludeKeywords": { "type": "array", "items": { "type": "string" } }, "platforms": { "type": "array", "items": { "type": "string", "enum": [ "instagram", "tiktok", "youtube" ] } }, "status": { "type": "string", "enum": [ "idle", "running", "completed", "failed" ] }, "progresso": { "type": [ "number", "null" ] }, "etapa": { "type": [ "string", "null" ] }, "criadoEm": { "type": "string", "description": "Instante em ISO-8601 UTC, ex. 2026-09-11T12:00:00.000Z" }, "ultimaRodadaEm": { "anyOf": [ { "type": "string", "description": "Instante em ISO-8601 UTC, ex. 2026-09-11T12:00:00.000Z" }, { "type": "null" } ] }, "custoUsd": { "type": [ "number", "null" ] }, "dataIntelligence": { "type": "boolean" }, "metaAds": { "type": "boolean" }, "recorrente": { "type": "boolean" }, "cadencia": { "type": [ "string", "null" ] }, "fonteId": { "type": [ "string", "null" ] }, "contagens": { "anyOf": [ { "type": "object", "properties": { "videos": { "type": "number" }, "videosTotal": { "type": "number" }, "criadores": { "type": "number" }, "ganchos": { "type": "number" }, "sons": { "type": "number" }, "hashtags": { "type": "number" }, "anuncios": { "type": "number" }, "tendencias": { "type": "number" }, "benchmarks": { "type": "number" }, "analise": { "type": "boolean" } }, "required": [ "videos", "videosTotal", "criadores", "ganchos", "sons", "hashtags", "anuncios", "tendencias", "benchmarks", "analise" ], "additionalProperties": false }, { "type": "null" } ], "description": "null enquanto não há resultado" }, "traducao": { "anyOf": [ { "type": "object", "properties": { "total": { "type": "number" }, "traduzidas": { "type": "number" } }, "required": [ "total", "traduzidas" ], "additionalProperties": false }, { "type": "null" } ] }, "custo": { "type": "object", "properties": { "usd": { "type": "number", "description": "O valor cobrado nesta chamada, em dólares" }, "fonte": { "type": "string", "enum": [ "x-cost", "cache", "ia-do-pico" ], "description": "x-cost = header real da fonte; cache = a fonte não cobrou; ia-do-pico = IA paga pelo Pico, não pela sua conta" } }, "required": [ "usd", "fonte" ], "additionalProperties": false }, "proximoPasso": { "type": "string" } }, "required": [ "id", "nome", "intent", "keywords", "excludeKeywords", "platforms", "status", "progresso", "etapa", "criadoEm", "ultimaRodadaEm", "custoUsd", "dataIntelligence", "metaAds", "recorrente", "cadencia", "fonteId", "contagens", "traducao", "custo", "proximoPasso" ], "additionalProperties": false }, "Taxonomias": { "type": "object", "properties": { "tiposDeGancho": { "anyOf": [ {}, { "type": "null" } ] }, "tiposVisuais": { "anyOf": [ {}, { "type": "null" } ] }, "categorias": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "hookCount": { "type": "number" } }, "required": [ "slug", "name", "hookCount" ], "additionalProperties": false } }, "regioes": { "type": "array", "items": {} } }, "required": [ "tiposDeGancho", "tiposVisuais", "categorias", "regioes" ], "additionalProperties": false }, "SugerirKeywordsEntrada": { "type": "object", "properties": { "intent": { "type": "string", "minLength": 1, "maxLength": 2000 }, "platforms": { "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "tiktok", "youtube", "instagram" ] } } }, "required": [ "intent" ] }, "Keywords": { "type": "object", "properties": { "keywords": { "type": "array", "items": { "type": "string" } }, "excludeKeywords": { "type": "array", "items": { "type": "string" } }, "reasoning": { "type": "string", "description": "O porquê das keywords, em português quando a IA do Pico conseguiu traduzir" }, "reasoningIdioma": { "type": "string", "enum": [ "pt", "en" ] }, "quality": { "type": "object", "properties": { "score": { "type": "number" }, "passes": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "string" } } }, "required": [ "score", "passes", "issues" ], "additionalProperties": false } }, "required": [ "keywords", "excludeKeywords", "reasoning", "reasoningIdioma", "quality" ], "additionalProperties": false }, "MelhorarIntentEntrada": { "type": "object", "properties": { "descricao": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "descricao" ] }, "IntentMelhorado": { "type": "object", "properties": { "intent": { "type": "string" }, "custo": { "type": "object", "properties": { "usd": { "type": "number", "description": "O valor cobrado nesta chamada, em dólares" }, "fonte": { "type": "string", "enum": [ "x-cost", "cache", "ia-do-pico" ], "description": "x-cost = header real da fonte; cache = a fonte não cobrou; ia-do-pico = IA paga pelo Pico, não pela sua conta" } }, "required": [ "usd", "fonte" ], "additionalProperties": false } }, "required": [ "intent", "custo" ], "additionalProperties": false }, "PesquisaCartao": { "type": "object", "properties": { "id": { "type": "string" }, "nome": { "type": "string" }, "intent": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" } }, "excludeKeywords": { "type": "array", "items": { "type": "string" } }, "platforms": { "type": "array", "items": { "type": "string", "enum": [ "instagram", "tiktok", "youtube" ] } }, "status": { "type": "string", "enum": [ "idle", "running", "completed", "failed" ] }, "progresso": { "type": [ "number", "null" ] }, "etapa": { "type": [ "string", "null" ] }, "criadoEm": { "type": "string", "description": "Instante em ISO-8601 UTC, ex. 2026-09-11T12:00:00.000Z" }, "ultimaRodadaEm": { "anyOf": [ { "type": "string", "description": "Instante em ISO-8601 UTC, ex. 2026-09-11T12:00:00.000Z" }, { "type": "null" } ] }, "custoUsd": { "type": [ "number", "null" ] }, "dataIntelligence": { "type": "boolean" }, "metaAds": { "type": "boolean" }, "recorrente": { "type": "boolean" }, "cadencia": { "type": [ "string", "null" ] }, "fonteId": { "type": [ "string", "null" ] }, "contagens": { "anyOf": [ { "type": "object", "properties": { "videos": { "type": "number" }, "videosTotal": { "type": "number" }, "criadores": { "type": "number" }, "ganchos": { "type": "number" }, "sons": { "type": "number" }, "hashtags": { "type": "number" }, "anuncios": { "type": "number" }, "tendencias": { "type": "number" }, "benchmarks": { "type": "number" }, "analise": { "type": "boolean" } }, "required": [ "videos", "videosTotal", "criadores", "ganchos", "sons", "hashtags", "anuncios", "tendencias", "benchmarks", "analise" ], "additionalProperties": false }, { "type": "null" } ], "description": "null enquanto não há resultado" }, "traducao": { "anyOf": [ { "type": "object", "properties": { "total": { "type": "number" }, "traduzidas": { "type": "number" } }, "required": [ "total", "traduzidas" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "nome", "intent", "keywords", "excludeKeywords", "platforms", "status", "progresso", "etapa", "criadoEm", "ultimaRodadaEm", "custoUsd", "dataIntelligence", "metaAds", "recorrente", "cadencia", "fonteId", "contagens", "traducao" ], "additionalProperties": false }, "Recurso": { "type": "object", "properties": { "id": { "type": "string" }, "recurso": { "type": "string" }, "idioma": { "type": "string", "enum": [ "pt", "en" ] }, "traducao": { "type": "object", "properties": { "total": { "type": "number" }, "traduzidas": { "type": "number" } }, "required": [ "total", "traduzidas" ], "additionalProperties": false }, "paraTraduzir": { "type": "string" }, "itens": { "type": "array", "items": {} }, "analise": {} }, "required": [ "id", "recurso", "idioma", "traducao", "paraTraduzir" ], "additionalProperties": {}, "description": "O recorte pedido. `itens` para listas (videos, ganchos…); `analise` para o relatório" }, "RelatorioTraducao": { "type": "object", "properties": { "id": { "type": "string" }, "completa": { "type": "boolean" }, "total": { "type": "number" }, "traduzidas": { "type": "number" }, "novas": { "type": "number" }, "chamadas": { "type": "number" }, "pendentes": { "type": "number" }, "erro": { "type": "string" }, "mapa": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "frase original → tradução" } }, "required": [ "id", "completa", "total", "traduzidas", "novas", "chamadas", "pendentes", "mapa" ], "additionalProperties": false }, "Analise": { "type": "object", "properties": { "id": { "type": "string" }, "analise": { "type": "object", "properties": { "summary": { "type": "string" }, "topThemes": { "type": "array", "items": { "type": "string" } }, "contentStrategy": { "type": "array", "items": { "type": "string" } }, "hookPatterns": { "type": "array", "items": { "type": "string" } }, "postingAdvice": { "type": "array", "items": { "type": "string" } }, "sentiment": { "type": "object", "properties": { "positive": { "type": "number" }, "neutral": { "type": "number" }, "negative": { "type": "number" } }, "required": [ "positive", "neutral", "negative" ], "additionalProperties": false } }, "required": [ "summary", "topThemes", "contentStrategy", "hookPatterns", "postingAdvice" ], "additionalProperties": false }, "custo": { "type": "object", "properties": { "usd": { "type": "number", "description": "O valor cobrado nesta chamada, em dólares" }, "fonte": { "type": "string", "enum": [ "x-cost", "cache", "ia-do-pico" ], "description": "x-cost = header real da fonte; cache = a fonte não cobrou; ia-do-pico = IA paga pelo Pico, não pela sua conta" } }, "required": [ "usd", "fonte" ], "additionalProperties": false } }, "required": [ "id", "analise", "custo" ], "additionalProperties": false }, "Criadores": { "type": "object", "properties": { "satelites": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "handle": { "type": "string" }, "platform": { "type": "string", "enum": [ "instagram", "tiktok", "youtube" ] }, "criadoEm": { "type": "string", "description": "Instante em ISO-8601 UTC, ex. 2026-09-11T12:00:00.000Z" }, "perfil": {}, "videos": { "type": "number" }, "relatorio": { "type": [ "string", "null" ] }, "fonteJobId": { "type": [ "string", "null" ] } }, "required": [ "id", "handle", "platform", "criadoEm", "perfil", "videos", "relatorio", "fonteJobId" ], "additionalProperties": false } }, "monitorados": { "type": "array", "items": {} }, "videosMonitorados": { "type": "array", "items": {} } }, "required": [ "satelites", "monitorados", "videosMonitorados" ], "additionalProperties": false }, "SateliteEntrada": { "type": "object", "properties": { "handle": { "type": "string", "minLength": 1, "maxLength": 120 }, "platform": { "type": "string", "enum": [ "tiktok", "youtube", "instagram" ] }, "confirmarGasto": { "type": "boolean" } }, "required": [ "handle", "platform" ] }, "SateliteCriado": { "type": "object", "properties": { "id": { "type": "string" }, "handle": { "type": "string" }, "platform": { "type": "string", "enum": [ "instagram", "tiktok", "youtube" ] }, "status": { "type": "string" }, "custo": { "type": "object", "properties": { "usd": { "type": "number", "description": "O valor cobrado nesta chamada, em dólares" }, "fonte": { "type": "string", "enum": [ "x-cost", "cache", "ia-do-pico" ], "description": "x-cost = header real da fonte; cache = a fonte não cobrou; ia-do-pico = IA paga pelo Pico, não pela sua conta" } }, "required": [ "usd", "fonte" ], "additionalProperties": false }, "proximoPasso": { "type": "string" } }, "required": [ "id", "handle", "platform", "status", "custo", "proximoPasso" ], "additionalProperties": false }, "Satelite": { "type": "object", "properties": { "status": { "type": "string", "description": "processing | completed" }, "id": { "type": "string" }, "handle": { "type": "string" }, "platform": { "type": "string", "enum": [ "instagram", "tiktok", "youtube" ] }, "profile": { "type": "object", "properties": { "followers": { "type": "number" }, "engagementRate": { "type": "number" }, "category": { "type": "string" } }, "required": [ "followers", "engagementRate", "category" ], "additionalProperties": {} }, "videos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "platform": { "type": "string", "enum": [ "instagram", "tiktok", "youtube" ] }, "title": { "type": "string" }, "hookText": { "type": "string", "description": "A fala do criador nos primeiros segundos — nunca traduzida" }, "hookType": { "type": "string" }, "views": { "type": "number" }, "likes": { "type": "number" }, "comments": { "type": "number" }, "shares": { "type": "number" }, "publishDate": { "type": "string" }, "authorHandle": { "type": "string" }, "authorFollowers": { "type": "number" }, "outlierRatio": { "type": "number", "description": "views ÷ mediana do criador" }, "weightedScore": { "type": "number", "description": "Virality Score" }, "language": { "type": "string", "enum": [ "pt", "en" ] }, "region": { "type": "string" }, "intelligence": { "description": "Só com inteligência por vídeo; narrativa traduzível", "type": "object", "properties": { "primaryTopic": { "type": "string" }, "summary": { "type": "string" } }, "required": [ "primaryTopic", "summary" ], "additionalProperties": {} } }, "required": [ "id", "url", "platform", "title", "hookText", "hookType", "views", "likes", "comments", "shares", "publishDate", "authorHandle", "authorFollowers", "outlierRatio", "weightedScore", "language", "region" ], "additionalProperties": {} } }, "report": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "description": "Instante em ISO-8601 UTC, ex. 2026-09-11T12:00:00.000Z" } }, "required": [ "status", "id", "handle", "platform", "profile", "videos", "createdAt" ], "additionalProperties": {} }, "MonitorarEntrada": { "type": "object", "properties": { "handle": { "type": "string", "minLength": 1, "maxLength": 120 }, "platform": { "type": "string", "enum": [ "tiktok", "youtube", "instagram" ] }, "cadence": { "type": "string", "enum": [ "weekly", "bi_weekly", "monthly", "every_other_day" ] }, "confirmarGasto": { "type": "boolean" } }, "required": [ "handle", "platform" ] }, "MonitoradoCriado": { "type": "object", "properties": { "id": { "type": "string" }, "handle": { "type": "string" }, "platform": { "type": "string", "enum": [ "instagram", "tiktok", "youtube" ] }, "status": { "type": "string" }, "custo": { "type": "object", "properties": { "usd": { "type": "number", "description": "O valor cobrado nesta chamada, em dólares" }, "fonte": { "type": "string", "enum": [ "x-cost", "cache", "ia-do-pico" ], "description": "x-cost = header real da fonte; cache = a fonte não cobrou; ia-do-pico = IA paga pelo Pico, não pela sua conta" } }, "required": [ "usd", "fonte" ], "additionalProperties": false } }, "required": [ "id", "handle", "platform", "status", "custo" ], "additionalProperties": false }, "Briefing": { "type": "object", "properties": { "id": { "type": "string" }, "briefing": { "type": "string" }, "custo": { "type": "object", "properties": { "usd": { "type": "number", "description": "O valor cobrado nesta chamada, em dólares" }, "fonte": { "type": "string", "enum": [ "x-cost", "cache", "ia-do-pico" ], "description": "x-cost = header real da fonte; cache = a fonte não cobrou; ia-do-pico = IA paga pelo Pico, não pela sua conta" } }, "required": [ "usd", "fonte" ], "additionalProperties": false } }, "required": [ "id", "briefing", "custo" ], "additionalProperties": false }, "CriarPecaEntrada": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "script", "brief", "hooks", "carousel", "legenda" ] }, "brief": { "type": "string", "minLength": 1, "maxLength": 20000 }, "titulo": { "type": "string", "maxLength": 300 }, "provenance": { "type": "object", "properties": { "hookText": { "type": "string", "minLength": 1, "maxLength": 2000 }, "creatorHandle": { "type": "string", "maxLength": 120 }, "creatorPlatform": { "type": "string", "enum": [ "tiktok", "youtube", "instagram" ] }, "outlierRatio": { "type": "number", "minimum": 0, "maximum": 100000 }, "sourceVideoId": { "type": "string", "maxLength": 200 }, "nicheId": { "type": "string", "maxLength": 200 }, "nicheLabel": { "type": "string", "maxLength": 300 } }, "required": [ "hookText" ] } }, "required": [ "kind", "brief" ] }, "Peca": { "anyOf": [ { "type": "object", "properties": { "origem": { "type": "string", "const": "rascunho" }, "id": { "type": "string" }, "title": { "type": "string" }, "kind": { "type": "string", "enum": [ "script", "brief", "hooks", "carousel", "legenda" ] }, "sourceLabel": { "type": "string" }, "body": { "type": "string", "description": "Roteiro/brief/ganchos/legenda em texto; carrossel em JSON {slides:[{titulo,texto}]}" }, "createdAt": { "type": "string", "description": "Instante em ISO-8601 UTC, ex. 2026-09-11T12:00:00.000Z" }, "provenance": { "type": "object", "properties": { "hookText": { "type": "string" }, "creatorHandle": { "type": "string" }, "creatorPlatform": { "type": "string", "enum": [ "instagram", "tiktok", "youtube" ] }, "outlierRatio": { "type": "number" }, "sourceVideoId": { "type": "string" }, "nicheId": { "type": "string" }, "nicheLabel": { "type": "string" } }, "required": [ "hookText" ], "additionalProperties": false } }, "required": [ "origem", "id", "title", "kind", "sourceLabel", "body", "createdAt" ], "additionalProperties": false }, { "type": "object", "properties": { "origem": { "type": "string", "const": "calendario" }, "id": { "type": "string" }, "clientId": { "type": "string" }, "title": { "type": "string" }, "kind": { "type": "string", "enum": [ "reel", "carousel", "story", "post" ] }, "status": { "type": "string", "enum": [ "local_draft", "ready", "publishing", "published", "failed", "cancelled" ] }, "body": { "type": "string" }, "caption": { "type": "string" }, "scheduledAt": { "type": "string", "description": "Instante em ISO-8601 UTC, ex. 2026-09-11T12:00:00.000Z" }, "publishedAt": { "type": "string", "description": "Instante em ISO-8601 UTC, ex. 2026-09-11T12:00:00.000Z" }, "network": { "type": "string", "enum": [ "instagram", "tiktok", "youtube" ] }, "provenance": { "type": "object", "properties": { "hookText": { "type": "string" }, "creatorHandle": { "type": "string" }, "creatorPlatform": { "type": "string", "enum": [ "instagram", "tiktok", "youtube" ] }, "outlierRatio": { "type": "number" }, "sourceVideoId": { "type": "string" }, "nicheId": { "type": "string" }, "nicheLabel": { "type": "string" } }, "required": [ "hookText" ], "additionalProperties": false }, "metrics": { "type": "object", "properties": { "likes": { "type": "number" }, "comments": { "type": "number" }, "shares": { "type": "number" }, "saves": { "type": "number" }, "views": { "type": "number" } }, "required": [ "likes", "comments", "shares" ], "additionalProperties": false } }, "required": [ "origem", "id", "clientId", "title", "kind", "status", "body", "caption", "network" ], "additionalProperties": false } ] }, "EditarPecaEntrada": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300 }, "body": { "type": "string", "minLength": 1, "maxLength": 200000 } } }, "Rascunho": { "type": "object", "properties": { "origem": { "type": "string", "const": "rascunho" }, "id": { "type": "string" }, "title": { "type": "string" }, "kind": { "type": "string", "enum": [ "script", "brief", "hooks", "carousel", "legenda" ] }, "sourceLabel": { "type": "string" }, "body": { "type": "string", "description": "Roteiro/brief/ganchos/legenda em texto; carrossel em JSON {slides:[{titulo,texto}]}" }, "createdAt": { "type": "string", "description": "Instante em ISO-8601 UTC, ex. 2026-09-11T12:00:00.000Z" }, "provenance": { "type": "object", "properties": { "hookText": { "type": "string" }, "creatorHandle": { "type": "string" }, "creatorPlatform": { "type": "string", "enum": [ "instagram", "tiktok", "youtube" ] }, "outlierRatio": { "type": "number" }, "sourceVideoId": { "type": "string" }, "nicheId": { "type": "string" }, "nicheLabel": { "type": "string" } }, "required": [ "hookText" ], "additionalProperties": false } }, "required": [ "origem", "id", "title", "kind", "sourceLabel", "body", "createdAt" ], "additionalProperties": false }, "AgendarPecaEntrada": { "type": "object", "properties": { "dia": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "cta": { "type": "string", "maxLength": 500 }, "clientId": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "dia" ] }, "Agendada": { "type": "object", "properties": { "postId": { "type": "string" }, "studioId": { "type": "string" }, "dia": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Dia no formato AAAA-MM-DD" }, "status": { "type": "string", "const": "ready" } }, "required": [ "postId", "studioId", "dia", "status" ], "additionalProperties": false }, "PublicarEntrada": { "type": "object", "properties": { "confirmar": { "type": "boolean", "const": true } }, "required": [ "confirmar" ] }, "Publicada": { "type": "object", "properties": { "acao": { "type": "string", "enum": [ "publicado", "ja_publicado" ] }, "motivo": { "type": [ "string", "null" ] }, "socialapiPostId": { "type": [ "string", "null" ] }, "permalink": { "type": [ "string", "null" ] }, "statusPonte": { "type": [ "string", "null" ] } }, "required": [ "acao", "motivo", "socialapiPostId", "permalink", "statusPonte" ], "additionalProperties": false }, "ResponderEntrada": { "type": "object", "properties": { "texto": { "type": "string", "minLength": 1, "maxLength": 1000 }, "confirmar": { "type": "boolean", "const": true } }, "required": [ "texto", "confirmar" ] }, "Respondida": { "type": "object", "properties": { "acao": { "type": "string", "const": "enviado" }, "canal": { "type": "string", "enum": [ "comment", "dm" ] }, "motivo": { "type": [ "string", "null" ] }, "ref": { "type": [ "string", "null" ] } }, "required": [ "acao", "canal", "motivo", "ref" ], "additionalProperties": false }, "Inbox": { "type": "object", "properties": { "itens": { "type": "array", "items": {} }, "contas": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "nome": { "type": "string" }, "username": { "type": "string" }, "platform": { "type": "string" } }, "required": [ "id", "nome", "username", "platform" ], "additionalProperties": false } }, "mensagens": { "type": "array", "items": {} }, "observado": { "type": "boolean" }, "semConta": { "type": "boolean" } }, "additionalProperties": {} }, "Resultado": { "type": "object", "properties": { "itens": { "type": "array", "items": { "type": "object", "properties": { "origem": { "type": "string", "const": "calendario" }, "id": { "type": "string" }, "clientId": { "type": "string" }, "title": { "type": "string" }, "kind": { "type": "string", "enum": [ "reel", "carousel", "story", "post" ] }, "status": { "type": "string", "enum": [ "local_draft", "ready", "publishing", "published", "failed", "cancelled" ] }, "body": { "type": "string" }, "caption": { "type": "string" }, "scheduledAt": { "type": "string", "description": "Instante em ISO-8601 UTC, ex. 2026-09-11T12:00:00.000Z" }, "publishedAt": { "type": "string", "description": "Instante em ISO-8601 UTC, ex. 2026-09-11T12:00:00.000Z" }, "network": { "type": "string", "enum": [ "instagram", "tiktok", "youtube" ] }, "provenance": { "type": "object", "properties": { "hookText": { "type": "string" }, "creatorHandle": { "type": "string" }, "creatorPlatform": { "type": "string", "enum": [ "instagram", "tiktok", "youtube" ] }, "outlierRatio": { "type": "number" }, "sourceVideoId": { "type": "string" }, "nicheId": { "type": "string" }, "nicheLabel": { "type": "string" } }, "required": [ "hookText" ], "additionalProperties": false }, "metrics": { "type": "object", "properties": { "likes": { "type": "number" }, "comments": { "type": "number" }, "shares": { "type": "number" }, "saves": { "type": "number" }, "views": { "type": "number" } }, "required": [ "likes", "comments", "shares" ], "additionalProperties": false } }, "required": [ "origem", "id", "clientId", "title", "kind", "status", "body", "caption", "network" ], "additionalProperties": false } }, "totais": { "type": "object", "properties": { "likes": { "type": "number" }, "comments": { "type": "number" }, "shares": { "type": "number" }, "saves": { "type": "number" } }, "required": [ "likes", "comments", "shares", "saves" ], "additionalProperties": false }, "periodo": { "type": "object", "properties": { "de": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Dia no formato AAAA-MM-DD" }, { "type": "null" } ] }, "ate": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Dia no formato AAAA-MM-DD" }, { "type": "null" } ] } }, "required": [ "de", "ate" ], "additionalProperties": false } }, "required": [ "itens", "totais", "periodo" ], "additionalProperties": false } }, "examples": { "chave_invalida": { "summary": "Chave inválida", "value": { "type": "https://app.usepico.digital/docs/erros#chave_invalida", "title": "Chave inválida", "status": 401, "code": "chave_invalida", "detail": "A chave não existe, foi revogada, expirou ou o operador dela saiu do workspace. A resposta é a mesma nos quatro casos, de propósito." } }, "sem_sessao": { "summary": "Sem sessão", "value": { "type": "https://app.usepico.digital/docs/erros#sem_sessao", "title": "Sem sessão", "status": 401, "code": "sem_sessao", "detail": "A rota aceita só sessão do app (cookie) e a request veio sem ela." } }, "escopo_insuficiente": { "summary": "Escopo insuficiente", "value": { "type": "https://app.usepico.digital/docs/erros#escopo_insuficiente", "title": "Escopo insuficiente", "status": 403, "code": "escopo_insuficiente", "detail": "A chave não tem o escopo que a rota exige (leitura, escrita, gasto ou publicacao)." } }, "limite_excedido": { "summary": "Limite de chamadas", "value": { "type": "https://app.usepico.digital/docs/erros#limite_excedido", "title": "Limite de chamadas", "status": 429, "code": "limite_excedido", "detail": "A chave passou do limite da classe (ver /docs/limites). `Retry-After` diz quantos segundos esperar." } }, "erro_interno": { "summary": "Erro interno", "value": { "type": "https://app.usepico.digital/docs/erros#erro_interno", "title": "Erro interno", "status": 500, "code": "erro_interno", "detail": "Algo quebrou do nosso lado. O detalhe foi para o log, não para cá." } }, "so_sessao": { "summary": "Só com sessão", "value": { "type": "https://app.usepico.digital/docs/erros#so_sessao", "title": "Só com sessão", "status": 403, "code": "so_sessao", "detail": "A rota é de gestão da própria chave (criar, listar, revogar) e foi chamada com chave de API — chave não cria chave." } }, "cross_site": { "summary": "Request cross-site", "value": { "type": "https://app.usepico.digital/docs/erros#cross_site", "title": "Request cross-site", "status": 403, "code": "cross_site", "detail": "Request com sessão vinda de outro site por script (fetch/XHR). Só o próprio app pode usar a sessão." } }, "corpo_invalido": { "summary": "Corpo inválido", "value": { "type": "https://app.usepico.digital/docs/erros#corpo_invalido", "title": "Corpo inválido", "status": 400, "code": "corpo_invalido", "detail": "O JSON não é válido ou não passa na validação do campo (o `detail` diz qual)." } }, "nao_encontrado": { "summary": "Não encontrado", "value": { "type": "https://app.usepico.digital/docs/erros#nao_encontrado", "title": "Não encontrado", "status": 404, "code": "nao_encontrado", "detail": "O recurso não existe — ou pertence a outro workspace, que responde igual (não revelamos que o id é válido)." } }, "rede_invalida": { "summary": "Rede inválida", "value": { "type": "https://app.usepico.digital/docs/erros#rede_invalida", "title": "Rede inválida", "status": 400, "code": "rede_invalida", "detail": "A rede não é instagram, tiktok ou youtube." } }, "termo_pendente": { "summary": "Termo de conexão não aceito", "value": { "type": "https://app.usepico.digital/docs/erros#termo_pendente", "title": "Termo de conexão não aceito", "status": 403, "code": "termo_pendente", "detail": "A pessoa dona da chave ainda não aceitou o termo de conexão de contas (versão vigente) no app." } }, "ponte_nao_configurada": { "summary": "Ponte não configurada", "value": { "type": "https://app.usepico.digital/docs/erros#ponte_nao_configurada", "title": "Ponte não configurada", "status": 409, "code": "ponte_nao_configurada", "detail": "A chave da ponte de publicação não está no ambiente." } }, "conexao_recusada": { "summary": "Conexão recusada pela ponte", "value": { "type": "https://app.usepico.digital/docs/erros#conexao_recusada", "title": "Conexão recusada pela ponte", "status": 409, "code": "conexao_recusada", "detail": "A ponte de publicação não iniciou a conexão da rede (limite de perfis do plano, brand inválida, ponte fora). O `detail` traz o motivo e `codigoDaPonte` o código dela." } }, "limite_do_plano": { "summary": "Limite do plano", "value": { "type": "https://app.usepico.digital/docs/erros#limite_do_plano", "title": "Limite do plano", "status": 409, "code": "limite_do_plano", "detail": "O plano do workspace (Grátis, Pro ou Agência) não comporta mais um deste recurso — nichos, posts, criações, marcas, concorrentes — ou não inclui a ação (publicar no Grátis). O `detail` diz o uso, o limite e o plano que destrava." } }, "ia_indisponivel": { "summary": "IA indisponível", "value": { "type": "https://app.usepico.digital/docs/erros#ia_indisponivel", "title": "IA indisponível", "status": 502, "code": "ia_indisponivel", "detail": "O provedor de IA falhou ou está sem crédito." } }, "parametro_invalido": { "summary": "Parâmetro inválido", "value": { "type": "https://app.usepico.digital/docs/erros#parametro_invalido", "title": "Parâmetro inválido", "status": 400, "code": "parametro_invalido", "detail": "Um parâmetro de caminho ou de query está fora do formato (id, cursor, data)." } }, "idempotencia_invalida": { "summary": "Idempotency-Key inválida", "value": { "type": "https://app.usepico.digital/docs/erros#idempotencia_invalida", "title": "Idempotency-Key inválida", "status": 400, "code": "idempotencia_invalida", "detail": "O header veio vazio ou com mais de 200 caracteres." } }, "gasto_nao_confirmado": { "summary": "Gasto não confirmado", "value": { "type": "https://app.usepico.digital/docs/erros#gasto_nao_confirmado", "title": "Gasto não confirmado", "status": 409, "code": "gasto_nao_confirmado", "detail": "A rota cobra da conta (fonte ou IA) e o corpo não trouxe `confirmarGasto: true`. O `detail` diz o valor." } }, "teto_do_mes": { "summary": "Teto do mês", "value": { "type": "https://app.usepico.digital/docs/erros#teto_do_mes", "title": "Teto do mês", "status": 409, "code": "teto_do_mes", "detail": "A chamada estouraria o teto de gasto do mês configurado em Conta → Custo." } }, "fonte_indisponivel": { "summary": "Fonte de pesquisa indisponível", "value": { "type": "https://app.usepico.digital/docs/erros#fonte_indisponivel", "title": "Fonte de pesquisa indisponível", "status": 502, "code": "fonte_indisponivel", "detail": "A fonte falhou ou a chave dela está ausente/sem saldo." } }, "pesquisa_em_andamento": { "summary": "Pesquisa em andamento", "value": { "type": "https://app.usepico.digital/docs/erros#pesquisa_em_andamento", "title": "Pesquisa em andamento", "status": 409, "code": "pesquisa_em_andamento", "detail": "O resultado pedido ainda não existe: a pesquisa está rodando." } }, "peca_desconhecida": { "summary": "Peça desconhecida", "value": { "type": "https://app.usepico.digital/docs/erros#peca_desconhecida", "title": "Peça desconhecida", "status": 404, "code": "peca_desconhecida", "detail": "A peça não existe ou é de outro workspace." } }, "peca_nao_e_rascunho": { "summary": "Peça não é rascunho", "value": { "type": "https://app.usepico.digital/docs/erros#peca_nao_e_rascunho", "title": "Peça não é rascunho", "status": 409, "code": "peca_nao_e_rascunho", "detail": "Editar só vale para rascunho; a peça já é compromisso no calendário." } }, "kind_nao_publica": { "summary": "Formato não publicável", "value": { "type": "https://app.usepico.digital/docs/erros#kind_nao_publica", "title": "Formato não publicável", "status": 400, "code": "kind_nao_publica", "detail": "Brief e lista de ganchos não vão para o calendário." } }, "confirmacao_ausente": { "summary": "Confirmação ausente", "value": { "type": "https://app.usepico.digital/docs/erros#confirmacao_ausente", "title": "Confirmação ausente", "status": 400, "code": "confirmacao_ausente", "detail": "Publicar e responder agem na conta de um terceiro e exigem `confirmar: true` literal no corpo." } }, "recusado": { "summary": "Recusado pelo motor", "value": { "type": "https://app.usepico.digital/docs/erros#recusado", "title": "Recusado pelo motor", "status": 400, "code": "recusado", "detail": "O motor de publicação recusou antes de tocar a rede (falta de confirmação explícita ou peça inválida). O `detail` diz o motivo." } }, "em_andamento": { "summary": "Em andamento", "value": { "type": "https://app.usepico.digital/docs/erros#em_andamento", "title": "Em andamento", "status": 409, "code": "em_andamento", "detail": "A peça já está sendo publicada por outra chamada." } }, "sem_conta": { "summary": "Sem conta conectada", "value": { "type": "https://app.usepico.digital/docs/erros#sem_conta", "title": "Sem conta conectada", "status": 409, "code": "sem_conta", "detail": "O workspace não tem conta da rede conectada e ativa." } }, "sem_midia": { "summary": "Sem mídia", "value": { "type": "https://app.usepico.digital/docs/erros#sem_midia", "title": "Sem mídia", "status": 409, "code": "sem_midia", "detail": "A peça não tem imagem/vídeo acessível pelo servidor; a rede não aceita post sem mídia." } }, "adiado": { "summary": "Adiado", "value": { "type": "https://app.usepico.digital/docs/erros#adiado", "title": "Adiado", "status": 429, "code": "adiado", "detail": "O teto de publicações/interações da conta na rede foi atingido; o cron tenta depois." } }, "falhou": { "summary": "A ponte falhou", "value": { "type": "https://app.usepico.digital/docs/erros#falhou", "title": "A ponte falhou", "status": 502, "code": "falhou", "detail": "A rede/ponte respondeu erro. O `detail` traz o motivo e o `requestId` para o suporte." } }, "canal_invalido": { "summary": "Canal inválido", "value": { "type": "https://app.usepico.digital/docs/erros#canal_invalido", "title": "Canal inválido", "status": 400, "code": "canal_invalido", "detail": "O lead não é de comentário nem de DM respondível." } }, "ja_respondido": { "summary": "Já respondido", "value": { "type": "https://app.usepico.digital/docs/erros#ja_respondido", "title": "Já respondido", "status": 409, "code": "ja_respondido", "detail": "Este lead já recebeu resposta (a rede permite 1 private reply por comentário)." } }, "janela_fechada": { "summary": "Janela fechada", "value": { "type": "https://app.usepico.digital/docs/erros#janela_fechada", "title": "Janela fechada", "status": 409, "code": "janela_fechada", "detail": "Passaram 7 dias do comentário (private reply) ou 24 h da última DM: a rede não aceita mais resposta." } }, "sem_post": { "summary": "Sem post", "value": { "type": "https://app.usepico.digital/docs/erros#sem_post", "title": "Sem post", "status": 409, "code": "sem_post", "detail": "O comentário é de um post que o Pico não conhece." } }, "sem_conversa": { "summary": "Sem conversa", "value": { "type": "https://app.usepico.digital/docs/erros#sem_conversa", "title": "Sem conversa", "status": 409, "code": "sem_conversa", "detail": "A DM não tem conversa aberta na ponte." } }, "cota_esgotada": { "summary": "Cota de interações esgotada", "value": { "type": "https://app.usepico.digital/docs/erros#cota_esgotada", "title": "Cota de interações esgotada", "status": 429, "code": "cota_esgotada", "detail": "A conta gastou as interações do período na rede." } } } } }