---
title: 'REST API'
description: 'Tokens, acesso Bearer, exemplo de requisição e links para a referência OpenAPI.'
type: doc
locale: pt-BR
canonical: 'https://yoseno.com/pt-BR/docs/integrations/rest-api'
updated: '2026-07-30'
---

# REST API

Tokens, acesso Bearer, exemplo de requisição e links para a referência OpenAPI.

A REST API fica disponível em `/api/v1` e serve para scripts, serviços internos, CI,
exportações e outra automação no servidor.

Para endpoints protegidos, é necessário um token de API pessoal. A requisição é feita em nome
do usuário que emitiu o token e passa pelas mesmas verificações de papéis e permissões.

## Autorização

Envie o token no cabeçalho HTTP:

```http
Authorization: Bearer <token>
```

Como emitir, armazenar e revogar tokens está descrito no artigo
[Tokens de API](https://yoseno.com/pt-BR/docs/integrations/api-tokens.md).

## Exemplo de requisição

```bash
curl -sS "$PLATFORM_BASE_URL/api/v1/{org}/surveys" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $PLATFORM_API_TOKEN"
```

Substitua `{org}` pelo ID da organização. Os parâmetros do endpoint específico, o formato da resposta e os códigos de
erro estão na especificação completa.

## Limites de requisições

A API está protegida contra sobrecarga com limitação de taxa:
- API do aplicativo autenticado: 300 requisições por minuto por usuário ou IP.
- Webhook do provedor de pagamentos: 600 requisições por minuto.
- Endpoints públicos (`/status`, cartões da base de conhecimento): 300 requisições por minuto por IP.

Ao exceder o limite, o servidor retorna o HTTP `429 Too Many Requests` com o cabeçalho `Retry-After` (número de segundos até a nova tentativa) e o corpo do erro:

```json
{
  "status": 429,
  "message": "Muitas requisições. Tente novamente em 30 s.",
  "errors": {}
}
```

## Documentação completa

- [OpenAPI reference](https://yoseno.com/docs/api) — documentação interativa de endpoints, parâmetros e
  esquemas das respostas.
- [OpenAPI JSON](https://yoseno.com/docs/api.json) — um esquema legível por máquina para geradores de clientes, Postman,
  Insomnia e validações de contrato.

## Páginas relacionadas

- [/docs/api](https://yoseno.com/docs/api)
- [/docs/api.json](https://yoseno.com/docs/api.json)
- [Tokens de API](https://yoseno.com/pt-BR/docs/integrations/api-tokens.md) — Tokens pessoais e acesso bearer ao \`/api/v1\`.

## Leia a seguir

- [Sobre a base de conhecimento](https://yoseno.com/pt-BR/docs/knowledge.md) — Catálogo de práticas e conexão com as recomendações da plataforma.