> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appsignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API pública (V2)

A API pública (V2) é uma API REST para ler dados brutos da aplicação: métricas,
traces, logs, métricas de Kubernetes e estatísticas de deploy. Ela complementa a
[API GraphQL](/api/graphql), que gerencia modelos como apps, incidentes,
dashboards e alertas. Como regra geral, use a API REST para ler dados e
a API GraphQL para gerenciar configuração.

<Tip>
  Se você está construindo um agente ou assistente de IA, o [AppSignal MCP](/mcp-server)
  expõe esses dados diretamente aos agentes — você pode não precisar chamar esta API
  por conta própria.
</Tip>

## URL base

Todos os endpoints são servidos sob `/api/v2` no domínio `appsignal.com`:

<CodeGroup>
  ```shell Base URL theme={null}
  https://appsignal.com/api/v2
  ```
</CodeGroup>

## Autenticação

As requisições são autenticadas com seu token pessoal de API, passado como
bearer token ou como parâmetro de query. Você pode encontrar seu token na [tela de
configurações pessoais](https://appsignal.com/users/edit).

<CodeGroup>
  ```shell Authorization header theme={null}
  curl -H "Authorization: Bearer YOUR-PERSONAL-API-TOKEN" \
    https://appsignal.com/api/v2/metrics/names/YOUR-SITE-ID
  ```

  ```shell Query parameter theme={null}
  curl "https://appsignal.com/api/v2/metrics/names/YOUR-SITE-ID?token=YOUR-PERSONAL-API-TOKEN"
  ```
</CodeGroup>

Seu token dá acesso aos mesmos sites e organizações que você vê na
AppSignal. A maioria das requisições tem escopo de um único `site_id`; os endpoints de tracing usam
um array `site_ids` para que possam buscar em vários sites. A API verifica se
seu token tem acesso a todos os sites solicitados antes de retornar dados. Para verificar o
próprio token, chame `GET /api/v2/auth`.

Seu `site_id` é o ID na URL do seu app:
`https://appsignal.com/<organization>/sites/<SITE_ID>`. Para queries de log você também
precisa de um ID de fonte de log — veja [encontrando seus IDs de site e
fonte](/api/v2/logs#finding-your-site-and-source-ids).

## Verificar um token

<CodeGroup>
  ```shell Endpoint theme={null}
  GET /api/v2/auth
  ```
</CodeGroup>

Retorna um objeto JSON com uma `message` confirmando o ID do usuário autenticado.

## Requisições e respostas

A maioria dos endpoints usa `POST` com um corpo JSON e retorna JSON. Consultas somente leitura
(como listar nomes de métricas) usam `GET` com parâmetros de path. Defina
`Content-Type: application/json` em requisições com corpo.

Horários são strings ISO 8601. A maioria dos corpos de query recebe um intervalo de tempo `from` e `to`
mais um `site_id` ou, para endpoints de tracing, um array `site_ids`.

Para uma referência completa, gerada automaticamente, de cada endpoint, requisição e tipo de resposta,
consulte a [referência da API REST](https://appsignal.com/api/v2/docs).

## Respostas de erro

Qualquer endpoint pode retornar estas respostas não-2xx:

| Status | Significado                                     | Corpo                                    |
| ------ | ----------------------------------------------- | ---------------------------------------- |
| `401`  | Token ausente ou inválido                       | `{ "error": "Unauthorized" }`            |
| `404`  | Rota ou recurso não encontrado                  | `{ "error": "Not found" }`               |
| `422`  | Requisição parseada mas não pode ser processada | Envelope de erro (veja a seção a seguir) |
| `500`  | Falha não tratada no servidor                   | `{ "error": "<message>" }`               |

### Envelope 422

Toda resposta `422` usa o mesmo envelope, para que você possa tratá-las em um único lugar:

<CodeGroup>
  ```json 422 response theme={null}
  {
    "error": "<stable_slug>",
    "message": "<human-readable message>",
    "details": {}
  }
  ```
</CodeGroup>

* `error`: um slug estável, legível por máquina. Faça branching com base nele em seu código.
* `message`: uma mensagem legível por humanos, segura para exibir.
* `details`: um objeto opcional cujo formato depende de `error`.

Um slug que você pode encontrar é `legacy_log_query_syntax`, retornado quando uma query de logs
usa a sintaxe legada `attributes.<name>_<type>`. Veja [consultando
logs](/api/v2/logs) para a linguagem de query atual.

## Endpoints

### Métricas

| Método | Path                                                    | Descrição                                                           |
| ------ | ------------------------------------------------------- | ------------------------------------------------------------------- |
| `POST` | `/api/v2/metrics/timeseries`                            | Consultar dados de métrica como timeseries                          |
| `POST` | `/api/v2/metrics/list`                                  | Consultar dados agregados de métrica como uma lista com agrupamento |
| `GET`  | `/api/v2/metrics/names/{site_id}`                       | Listar todos os nomes de métrica de um site                         |
| `GET`  | `/api/v2/metrics/type_and_tags/{site_id}/{metric_name}` | Obter o tipo e as tags disponíveis de uma métrica                   |

Consulte a [referência de métricas](/api/v2/metrics).

### Tracing

| Método | Path                                  | Descrição                                             |
| ------ | ------------------------------------- | ----------------------------------------------------- |
| `POST` | `/api/v2/tracing/locator`             | Localizar um trace entre sites por trace ID           |
| `POST` | `/api/v2/tracing/trace`               | Obter todos os spans de um trace                      |
| `POST` | `/api/v2/tracing/trace/performance`   | Obter spans de um trace de performance                |
| `POST` | `/api/v2/tracing/trace/error`         | Obter spans de um trace de erro                       |
| `POST` | `/api/v2/tracing/traces/performance`  | Listar traces de performance                          |
| `POST` | `/api/v2/tracing/traces/errors`       | Listar traces de erro                                 |
| `POST` | `/api/v2/tracing/actions`             | Listar ações de performance com métricas agregadas    |
| `POST` | `/api/v2/tracing/action_edges`        | Listar arestas upstream e downstream de uma ação      |
| `POST` | `/api/v2/tracing/site_edges`          | Listar arestas de dependência de serviço para um site |
| `POST` | `/api/v2/tracing/slow_events`         | Listar eventos lentos com estatísticas agregadas      |
| `POST` | `/api/v2/tracing/slow_events/actions` | Listar ações relacionadas a um evento lento           |

Consulte a [referência de tracing](/api/v2/traces).

### Logs

| Método | Path                 | Descrição            |
| ------ | -------------------- | -------------------- |
| `POST` | `/api/v2/logs/lines` | Buscar linhas de log |

Consulte a [referência de logs](/api/v2/logs).

### Kubernetes

| Método | Path                               | Descrição                                         |
| ------ | ---------------------------------- | ------------------------------------------------- |
| `POST` | `/api/v2/kubernetes/nodes`         | Consultar métricas de node                        |
| `POST` | `/api/v2/kubernetes/pods`          | Consultar métricas de pod                         |
| `POST` | `/api/v2/kubernetes/pods/overview` | Consultar visão geral de pods com labels e status |

Consulte a [referência de Kubernetes](/api/v2/kubernetes).

### Deploys

| Método | Path                    | Descrição                                   |
| ------ | ----------------------- | ------------------------------------------- |
| `POST` | `/api/v2/deploys/stats` | Obter estatísticas de deploy de uma revisão |

Consulte a [referência de deploys](/api/v2/deploys).

### Check-ins

| Método | Path                          | Descrição                                          |
| ------ | ----------------------------- | -------------------------------------------------- |
| `POST` | `/api/v2/check_ins/test_cron` | Testar e validar uma expressão de agendamento cron |

Consulte a [referência de check-ins](/api/v2/check-ins).

### Visuais salvos

| Método | Path                             | Descrição                           |
| ------ | -------------------------------- | ----------------------------------- |
| `GET`  | `/api/v2/saved_visuals/{id}`     | Recuperar um visual salvo como JSON |
| `GET`  | `/api/v2/saved_visuals/{id}/csv` | Baixar um visual salvo como CSV     |

Os endpoints de visual salvo não exigem autenticação. Consulte a [referência de visuais
salvos](/api/v2/saved-visuals).

### Sistema

| Método | Path           | Descrição                      |
| ------ | -------------- | ------------------------------ |
| `GET`  | `/api/v2/auth` | Verificar se um token é válido |