---
title: Contrato e disponibilidade
description: Formatos comuns, autenticação e limites da prévia.
---
:::note[Versão publicada]
A Platform API v1 / 1.0.0 oferece 143 operações em produção e homologação, sujeitas à autorização, às capacidades e à configuração de cada provedor. Os exemplos usam recursos fictícios e homologação por padrão. O console inicia em sandbox; uma conexão real exige chave restrita do ambiente do portal.
:::

## Endereços e versões

Produção: `https://api.agilink.io/v1`. Homologação: `https://api.staging.agilink.io/v1`. Os dois servidores constam no OpenAPI. Não compartilhe credenciais ou IDs de recursos entre ambientes. O namespace administrativo preserva as rotas existentes do SDK. Leia [ambientes](/api/ambientes/) e [migração](/api/migracao-tokens/).

## Autenticação e permissão

Integrações de servidor usam uma chave com aplicativos permitidos, permissões específicas e prazo de expiração. Uma chave que pode ler links não pode emitir outras chaves nem acessar outro aplicativo. Operações de conta e gestão de credenciais exigem sessão humana.

Autorização delegada OAuth será acrescentada na Tarefa 2. O MCP usará a mesma política na Tarefa 3.

## Convenções

| Situação | Contrato novo |
| --- | --- |
| Sucesso JSON | `data` e `meta.requestId` |
| Falha JSON | `error.code`, `message`, `requestId`, `documentationUrl` |
| Lista | `data`, `pagination.nextCursor`, `pagination.hasMore` e `meta` |
| Alteração | `If-Match` com ETag atual; 428 se ausente, 412 se antigo |
| Mutação | `Idempotency-Key` UUID v4 por intenção; recibo por 24 horas |
| Exclusão concluída | 204, sem corpo |
| Limite excedido | 429 com `Retry-After` em segundos |

O cursor é vinculado ao aplicativo, à credencial, aos filtros, à ordem e ao limite. Para continuar, preserve esses valores. O cursor expira em 15 minutos; as listas não representam um snapshot transacional.

Chaves novas são exibidas uma única vez. Repetir a emissão confirmada preserva o efeito e retorna `409 secret_not_replayable`, sem reexibir nem criar outro segredo.

## Downloads

- [OpenAPI JSON consolidado](/contracts/openapi.json)
- [JSON Schema compartilhado](/contracts/schemas.json)
- [Catálogo das 143 operações previstas](/contracts/operations.json)
- [Permissões previstas](/contracts/permissions.json)

## Próximo passo

Leia a [receita de criação](/api/criar-link/) e explore a [referência OpenAPI](/referencia/). Consulte a [fundação em homologação](/api/fundacao/) para as 17 operações A2. Consulte o catálogo atual para os contratos de cada recurso.

Leia os [25 endpoints A3a](/api/endpoints-a3a/), o [guia de aplicativos, links e ativos](/api/apps-links-ativos/) e a [migração de tokens](/api/migracao-tokens/).

Consulte também os [45 endpoints A3b](/api/endpoints-a3b/) e o [ciclo de domínios, templates e publicação](/api/dominios-templates-publicacao/). A API totaliza 143 operações administrativas na versão publicada.

O A3c acrescenta [sete consultas de analytics](/api/endpoints-a3c/), com [cálculos e cobertura](/api/analytics/). A [referência pública do SDK](/contratos-publicos/) é separada e preserva seus formatos v1.