> ## 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 de Marcadores

Marcadores são pequenos ícones usados em gráficos para indicar uma alteração. Isso pode ser um
deploy usando um "Deploy marker" ou um evento personalizado com um "Custom marker".

Este endpoint de Marcador permite a criação e listagem de marcadores que estão
disponíveis por aplicação.

## Tipos de marcadores

### Deploy markers

Deploy markers são pequenos pontos na parte inferior de cada gráfico que indicam quando uma
nova revisão de uma aplicação foi implantada. Eles são uma ótima maneira de comparar
deploys entre si e ver se a nova versão aumentou ou diminuiu o desempenho
da aplicação.

Uma lista desses marcadores também é mostrada na página "Deploys" no AppSignal.com,
em um contexto de Aplicação.

<Tip>
  Para mais informações, leia também nossa [página de deploy
  markers](/application/markers/deploy-markers).
</Tip>

### Custom markers

Custom markers oferecem uma forma de adicionar mais contexto aos gráficos, permitindo que você adicione
anotações por conta própria. Crie um Custom marker para operações de escalonamento, quando houve
um pico repentino no tráfego ou quando um banco de dados estava com problemas.

<Tip>
  Para mais informações, leia também nossa [página de custom
  markers](/application/markers/custom-markers).
</Tip>

## Criação de marcador

Este endpoint permite a criação de Deploy e Custom markers.

Ao criar o payload para esta requisição, você pode selecionar qual tipo de marcador
criar especificando o valor `kind`.

|                      |                                |
| -------------------- | ------------------------------ |
| Endpoint             | `/api/\[app_id\]/markers.json` |
| Método da requisição | POST                           |
| Contexto             | Aplicações                     |
| Requer autenticação? | Sim                            |
| Formatos de resposta | JSON                           |

### Deploy marker

<Warning>
  Esse método de reportar marcadores de deploy está **obsoleto** e pode ser removido a qualquer momento no futuro.
  Reportar marcadores de deploy usando esse método só é útil para aplicações pequenas que usam uma única instância da aplicação. Ele cria um novo marcador de deploy em um momento específico, independentemente da versão que a aplicação está realmente executando. Isso também significa que é mais propenso a erros, agrupando dados que não deveriam pertencer ao deploy. Detectamos a implantação automaticamente lendo o arquivo `REVISION` que o Capistrano adiciona ao diretório de release desde a versão 4.5.18 da gem Ruby.
</Warning>

| Parâmetro   | Tipo                                                      | Descrição                                                                 |
| ----------- | --------------------------------------------------------- | ------------------------------------------------------------------------- |
| kind        | String                                                    | O tipo de marcador a ser criado - "deploy".                               |
| created\_at | Date - [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) | Horário em que inserir o marcador. Deixe vazio para usar o horário atual. |
| repository  | String                                                    | Link ou referência do Git, ex: "main".                                    |
| revision    | String                                                    | Referência de revisão do Git. Usado para criar links de git diff na UI.   |
| user        | String                                                    | Usuário que iniciou o deploy.                                             |

#### Exemplo de payload

<CodeGroup>
  ```json JSON theme={null}
  {
    "marker": {
      "kind": "deploy",
      "created_at": "2015-07-21T15:06:31.737+02:00",
      "repository": "git@github.com:company/repository.git",
      "revision": "fe001015311af4769a4dad76bdbce4c8f5d022af",
      "user": "user"
    }
  }
  ```
</CodeGroup>

#### Exemplo de payload com curl

<CodeGroup>
  ```bash Bash theme={null}
  curl -H "Content-Type: application/json" -XPOST https://appsignal.com/api/[app-id]/markers.json?token=[your-personal-token] \
    -d '{ "marker":{ "kind": "deploy", "repository": "git@github.com:company/repository.git", "revision": "[revision]", "user": "[user]"}}'
  ```
</CodeGroup>

Todas as requisições aos endpoints da API do AppSignal requerem um token de API pessoal fornecido como parâmetro de consulta na URL para [autenticação](/api#authentication).

### Custom marker

Usado para anotar eventos que podem impactar seu desempenho/taxa de erros. Exemplos são: aumento/diminuição de escala da infraestrutura na nuvem, manutenção no banco de dados, causa de picos de erros.

Se você quiser criar custom markers, mas não usar seu token de API pessoal, pode usar o [public endpoint](/api/public-endpoint/custom-markers).

| Parâmetro   | Tipo                                                      | Descrição                                                                               |
| ----------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| kind        | String                                                    | O tipo de marcador a ser criado - "custom".                                             |
| created\_at | Date - [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) | Horário em que inserir o marcador. Deixe vazio para usar o horário atual.               |
| icon        | String - Opcional                                         | Emoji a ser usado para este Custom marker, padrão é 🚀.                                 |
| message     | String - Opcional                                         | Mensagem mostrada ao passar o mouse sobre o marcador na UI. Truncada em 200 caracteres. |

#### Exemplo de payload

<CodeGroup>
  ```json JSON theme={null}
  {
    "marker": {
      "kind": "custom",
      "created_at": "2015-07-21T15:06:31.737+02:00",
      "icon": "💩",
      "message": "Accidentlly dropped production DB"
    }
  }
  ```
</CodeGroup>

## Listagem de marcadores

Este endpoint retorna uma lista de marcadores. Combina tanto Deploy quanto Custom
markers.

|                      |                                |
| -------------------- | ------------------------------ |
| Endpoint             | `/api/\[app_id\]/markers.json` |
| Método da requisição | `GET`                          |
| Contexto             | Aplicações                     |
| Requer autenticação? | Sim                            |
| Formatos de resposta | JSON                           |

### Parâmetros

| Parâmetro   | Tipo                                                                                 | Descrição                                                                  |
| ----------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
| kind        | String                                                                               | O tipo de marcador a ser criado - "custom".                                |
| from        | Date - [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) / Integer - timestamp UNIX | Todos os horários estão em UTC.                                            |
| to          | Date - [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) / Integer - timestamp UNIX | Todos os horários estão em UTC.                                            |
| limit       | Integer                                                                              | Limita o número de marcadores retornados.                                  |
| count\_only | Boolean                                                                              | Defina como "true" para retornar apenas o número de marcadores existentes. |

### Resposta

<CodeGroup>
  ```json JSON theme={null}
  {
    "count": 4212,
    "markers": [
      {
        "kind": "deploy",
        "id": "50a61f1b660cd3677775ccb0",
        "created_at": "2015-07-21T15:06:31.737+02:00",
        "closed_at": null,
        "live_for": 107413,
        "live_for_in_words": "1d",
        "gem_version": null,
        "repository": "git@github.com:company/repository.git",
        "revision": "fe001015311af4769a4dad76bdbce4c8f5d022af",
        "short_revision": "fe00101",
        "git_compare_url": "https://github.com/company/repository/compare/aaa...bbb",
        "user": "user",
        "exception_count": 200,
        "exception_rate": 8.81
      },
      {
        "kind": "custom",
        "icon": "💩",
        "message": "Accidentlly dropped production DB",
        "created_at": "2015-07-21T15:06:31.737+02:00"
      },
      {
        "kind": "notification",
        "message": "Appsignal API issues.",
        "created_at": "2015-07-21T15:06:31.737+02:00"
      }
    ]
  }
  ```
</CodeGroup>

Com `"count_only": true`.

<CodeGroup>
  ```json JSON theme={null}
  {
    "count": 4212
  }
  ```
</CodeGroup>

## Exibição de marcador

Este endpoint retorna a representação JSON de um único marcador.

|                      |                                              |
| -------------------- | -------------------------------------------- |
| Endpoint             | `/api/\[app_id\]/markers/\[marker_id\].json` |
| Método da requisição | `GET`                                        |
| Contexto             | Aplicações                                   |
| Requer autenticação? | Sim                                          |
| Formatos de resposta | JSON                                         |

### Parâmetros

| Parâmetro  | Tipo   | Descrição                         |
| ---------- | ------ | --------------------------------- |
| marker\_id | String | O id do marcador a ser retornado. |

### Resposta

A resposta para Deploy markers e Custom markers é diferente. Deploy markers
contêm mais dados sobre um determinado deploy, enquanto Custom markers contêm apenas os
dados fornecidos na criação.

#### Deploy marker

<CodeGroup>
  ```json JSON theme={null}
  {
    "id": "50a61f1b660cd3677775ccb0",
    "created_at": "2015-07-21T15:06:31.737+02:00",
    "closed_at": null,
    "live_for": 107413,
    "live_for_in_words": "1d",
    "gem_version": null,
    "repository": "git@github.com:company/repository.git",
    "revision": "fe001015311af4769a4dad76bdbce4c8f5d022af",
    "short_revision": "fe00101",
    "git_compare_url": "https://github.com/company/repository/compare/aaa...bbb",
    "user": "user",
    "exception_count": 200,
    "exception_rate": 8.81
  }
  ```
</CodeGroup>

#### Custom marker

<CodeGroup>
  ```json JSON theme={null}
  {
    "kind": "custom",
    "icon": "💩",
    "message": "Accidentlly dropped production DB",
    "created_at": "2015-07-21T15:06:31.737+02:00"
  }
  ```
</CodeGroup>

#### Notification marker

<CodeGroup>
  ```json JSON theme={null}
  {
    "kind": "notification",
    "message": "Appsignal API issues.",
    "created_at": "2015-07-21T15:06:31.737+02:00"
  }
  ```
</CodeGroup>

## Atualização de marcador

Este endpoint atualiza um único marcador e retorna a representação JSON do
marcador atualizado.

|                      |                                              |
| -------------------- | -------------------------------------------- |
| Endpoint             | `/api/\[app_id\]/markers/\[marker_id\].json` |
| Método da requisição | PUT                                          |
| Contexto             | Aplicações                                   |
| Requer autenticação? | Sim                                          |
| Formatos de resposta | JSON                                         |

### Parâmetros

| Parâmetro  | Tipo   | Descrição                          |
| ---------- | ------ | ---------------------------------- |
| marker\_id | String | O id do marcador a ser atualizado. |

### Payload

O payload é o mesmo de uma requisição [create/POST](#marker-create) e difere
por tipo de marcador.

### Resposta

A resposta é a mesma de uma requisição [show/GET](#marker-show) e difere por
tipo de marcador.

## Exclusão de marcador

Este endpoint exclui um único marcador.

|                      |                                              |
| -------------------- | -------------------------------------------- |
| Endpoint             | `/api/\[app_id\]/markers/\[marker_id\].json` |
| Método da requisição | DELETE                                       |
| Contexto             | Aplicações                                   |
| Requer autenticação? | Sim                                          |
| Formatos de resposta | JSON                                         |

### Parâmetros

| Parâmetro  | Tipo   | Descrição                        |
| ---------- | ------ | -------------------------------- |
| marker\_id | String | O id do marcador a ser excluído. |

### Resposta

O corpo da resposta desta requisição é vazio. O código de status retornará se a operação
foi bem-sucedida ou não.