# API da Promptado (/api)

Leve os dados de visibilidade das suas marcas nas IAs pro seu BI, planilha ou sistema.

A API da Promptado entrega por HTTP os mesmos dados que você vê no painel: visibilidade da marca nas respostas das IAs, prompts monitorados, concorrentes, fontes citadas, tráfego vindo das IAs, conteúdo do blog, auditorias e Google Search Console.

Ela serve pra quem quer:

* montar o próprio dashboard no Power BI, Looker Studio, Metabase ou planilha;
* cruzar a visibilidade nas IAs com dados de vendas, CRM ou mídia;
* guardar o histórico das respostas das IAs no seu data warehouse.

> **Só leitura**: A API só consulta dados. Nenhuma chamada cria, altera ou apaga nada na Promptado. Pra ativar prompts, cadastrar concorrentes ou gerar artigos, use a plataforma ou o [Coworker](/plataforma/coworker).

> **API ou MCP?**: Se você quer **perguntar** sobre os seus dados numa conversa com o Claude, o ChatGPT ou o Cursor, use o [Promptado MCP](/mcp). A API é pra **sistemas** que buscam os dados sozinhos, sem uma IA no meio.

## Quem tem acesso

A API é liberada por conta. Se a sua conta ainda não tem, fale com o nosso time. Com ela liberada, o item **API** aparece no menu da conta pros administradores.

A chave é da **conta**, não de uma pessoa: continua funcionando se quem criou sair da equipe. Ela enxerga todas as marcas ativas da conta. Em conta de agência, só as marcas com assinatura ativa.

## Primeira chamada

**Crie uma chave.** No app, abra o menu da conta, vá em **API** e clique em **Criar chave**. Veja [Chaves](/api/chaves).

**Liste as suas marcas.** O `id` de cada marca é o `brand_id` que os outros endpoints pedem, e `ais` diz quais IAs ela monitora.

```bash
curl https://app.promptado.com/api/v1/brands \
  -H "Authorization: Bearer $PROMPTADO_API_KEY"
```

**Busque a visibilidade de uma marca** nos últimos 30 dias:

```bash
curl "https://app.promptado.com/api/v1/brands/SEU_BRAND_ID/visibility?period=30d" \
  -H "Authorization: Bearer $PROMPTADO_API_KEY"
```

## O básico

- **Endereço base**: `https://app.promptado.com/api/v1`

- **Autenticação**: Cabeçalho 

`Authorization: Bearer pmt_api_...`

em toda chamada. A chave nunca vai na URL.

- **Formato**: JSON em UTF-8. Nomes de campo em 

`snake_case`

. Datas em 

`YYYY-MM-DD`

e data-hora em ISO 8601 (UTC).

- **Envelope**: Os dados vêm sempre em 

`data`

. Listas trazem também 

`next_cursor`

(veja 

[Paginação](/api/paginacao)

).

- **Período**: `period`

(

`today`

, 

`7d`

, 

`14d`

, 

`30d`

, 

`90d`

, 

`this_month`

, 

`last_month`

) OU 

`start_date`

\+ 

`end_date`

, com até 366 dias. Os dias seguem o horário de Brasília.

- **IA**: O filtro 

`ai`

aceita as IAs que aparecem no campo 

`ais`

da marca em 

`/brands`

, por exemplo 

`ChatGPT`

ou 

`GoogleAI`

(o Modo IA do Google). Sem ele, as IAs vêm somadas.

- **Parâmetros desconhecidos**: Recusados com erro 400. Um erro de digitação nunca devolve dados de outro período em silêncio.

- **Especificação**: OpenAPI 3 em 

[`/api/v1/openapi.json`](https://app.promptado.com/api/v1/openapi.json)

. Dá pra importar no Postman, no Insomnia ou gerar um cliente.

## O que tem na API

[Visibilidade](/api/referencia/visibilidade): Taxa de menção no período, por IA, contra o período anterior e dia a dia.

[Respostas](/api/referencia/respostas): Cada resposta das IAs, com menções e fontes, pra sincronizar com BI.

[Prompts](/api/referencia/prompts): Prompts monitorados, desempenho de cada um e as buscas que as IAs fazem.

[Concorrentes](/api/referencia/concorrentes): Cadastro e ranking de quem as IAs mais citam.

[Fontes](/api/referencia/fontes): Sites e páginas citadas, e presença em Shopping, mapas e X.

[Tráfego](/api/referencia/trafego): Visitas ao site vindas das IAs.