{ "openapi": "3.1.1", "info": { "title": "Agilink Platform API", "version": "1.0.0", "description": "143 operações administrativas. Produção e homologação têm credenciais, dados e capacidade próprios. OAuth e MCP ainda não estão disponíveis. Exemplos usam recursos fictícios.", "contact": { "name": "Projeto Agilink", "url": "https://agilink.io" } }, "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "servers": [ { "url": "https://api.agilink.io/v1", "description": "Produção — exige autorização do proprietário" }, { "url": "https://api.staging.agilink.io/v1", "description": "Homologação isolada — credenciais e dados próprios" } ], "security": [ { "HumanSession": [] } ], "tags": [ { "name": "me", "description": "Contratos de referência de me" }, { "name": "api-keys", "description": "Contratos de referência de api-keys" }, { "name": "links", "description": "Contratos de referência de links" }, { "name": "apps", "description": "Contratos de referência de apps" }, { "name": "assets", "description": "Contratos de referência de assets" }, { "name": "capabilities", "description": "Contratos de referência de capabilities" }, { "name": "audit-events", "description": "Contratos de referência de audit-events" }, { "name": "requests", "description": "Contratos de referência de requests" }, { "name": "operations", "description": "Contratos de referência de operations" } ], "paths": { "/me": { "get": { "operationId": "getMe", "summary": "Identidade mínima e contexto autorizado", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Chaves recebem identidade técnica mínima: displayName e photoUrl null; sem e-mail, sessão ou lista global de apps. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "me" ], "parameters": [], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "identity:read", "x-agilink-resource-scope": "principal", "x-agilink-milestone": "A2", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeEnvelope" }, "example": { "data": { "userId": "40000000-0000-4000-8000-000000000001", "displayName": "Ana", "photoUrl": null, "actorType": "human", "revision": "20000000-0000-4000-8000-000000000001" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "patch": { "operationId": "updateMe", "summary": "Atualizar nome/foto do perfil com o contrato permitido pelo produto", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. Exige sessão humana verificada. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "me" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "profile:update", "x-agilink-resource-scope": "subject_owned", "x-agilink-milestone": "A2", "x-agilink-future-oauth": "excluded", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MePatch" }, "example": { "displayName": "Ana" } } } }, "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeEnvelope" }, "example": { "data": { "userId": "40000000-0000-4000-8000-000000000001", "displayName": "Ana", "photoUrl": null, "actorType": "human", "revision": "20000000-0000-4000-8000-000000000001" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/me/preferences": { "get": { "operationId": "getMePreferences", "summary": "Consultar/alterar preferências do próprio usuário, incluindo app selecionado", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. Exige sessão humana verificada. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "me" ], "parameters": [], "security": [ { "HumanSession": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "preferences:read", "x-agilink-resource-scope": "subject_owned", "x-agilink-milestone": "A2", "x-agilink-future-oauth": "excluded", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreferencesEnvelope" }, "example": { "data": { "selectedAppId": "app_loja", "theme": "system", "revision": "20000000-0000-4000-8000-000000000001" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "patch": { "operationId": "updateMePreferences", "summary": "Consultar/alterar preferências do próprio usuário, incluindo app selecionado", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. Exige sessão humana verificada. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "me" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "preferences:update", "x-agilink-resource-scope": "subject_owned", "x-agilink-milestone": "A2", "x-agilink-future-oauth": "excluded", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreferencesPatch" }, "example": { "theme": "dark" } } } }, "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreferencesEnvelope" }, "example": { "data": { "selectedAppId": "app_loja", "theme": "system", "revision": "20000000-0000-4000-8000-000000000001" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/api-keys": { "post": { "operationId": "createApiKeys", "summary": "Emitir credencial limitada", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. Exige sessão humana verificada. Segredo somente na resposta inicial. Repetição do recibo confirmado retorna 409 secret_not_replayable e metadados sem novo segredo. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "api-keys" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." } ], "security": [ { "HumanSession": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "api_keys:create", "x-agilink-resource-scope": "subject_owned", "x-agilink-milestone": "A2", "x-agilink-future-oauth": "excluded", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreate" }, "example": { "name": "Backend da loja", "appIds": [ "app_loja" ], "permissions": [ "apps:read", "links:read", "links:create" ] } } } }, "responses": { "201": { "description": "Criado. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" }, "Location": { "description": "Endereço relativo do recurso criado.", "schema": { "type": "string" }, "example": "/v1/api-keys/30000000-0000-4000-8000-000000000001" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyIssuedEnvelope" }, "example": { "data": { "key": { "id": "30000000-0000-4000-8000-000000000001", "name": "Backend da loja", "prefix": "agl_test_AbCdEf", "appIds": [ "app_loja" ], "permissions": [ "apps:read", "links:read", "links:create" ], "expiresAt": "2027-01-17T20:00:00Z", "createdAt": "2026-10-19T20:00:00Z", "lastUsedAt": null, "revokedAt": null, "revision": "20000000-0000-4000-8000-000000000001" }, "secret": "agl_test_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Location": { "description": "Consulta da chave já emitida, quando houver.", "schema": { "type": "string" }, "example": "/v1/api-keys/30000000-0000-4000-8000-000000000001" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "secret_not_replayable", "message": "A chave já foi emitida. O segredo não pode ser reexibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#secret-not-replayable", "resource": { "type": "api_key", "id": "30000000-0000-4000-8000-000000000001" } } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "get": { "operationId": "getApiKeys", "summary": "Metadados das credenciais, sem segredo", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. Exige sessão humana verificada. Segredo somente na resposta inicial. Repetição do recibo confirmado retorna 409 secret_not_replayable e metadados sem novo segredo. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "api-keys" ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Cursor" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "security": [ { "HumanSession": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "api_keys:read", "x-agilink-resource-scope": "subject_owned", "x-agilink-milestone": "A2", "x-agilink-future-oauth": "excluded", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyListEnvelope" }, "example": { "data": [ { "id": "30000000-0000-4000-8000-000000000001", "name": "Backend da loja", "prefix": "agl_test_AbCdEf", "appIds": [ "app_loja" ], "permissions": [ "apps:read", "links:read", "links:create" ], "expiresAt": "2027-01-17T20:00:00Z", "createdAt": "2026-10-19T20:00:00Z", "lastUsedAt": null, "revokedAt": null, "revision": "20000000-0000-4000-8000-000000000001" } ], "pagination": { "nextCursor": null, "hasMore": false }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/api-keys/{keyId}": { "get": { "operationId": "getApiKeysKeyId", "summary": "Consultar/alterar metadados e restrições permitidas", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. Exige sessão humana verificada. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "api-keys" ], "parameters": [ { "name": "keyId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Revision" } } ], "security": [ { "HumanSession": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "api_keys:read", "x-agilink-resource-scope": "subject_owned", "x-agilink-milestone": "A2", "x-agilink-future-oauth": "excluded", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyEnvelope" }, "example": { "data": { "id": "30000000-0000-4000-8000-000000000001", "name": "Backend da loja", "prefix": "agl_test_AbCdEf", "appIds": [ "app_loja" ], "permissions": [ "apps:read", "links:read", "links:create" ], "expiresAt": "2027-01-17T20:00:00Z", "createdAt": "2026-10-19T20:00:00Z", "lastUsedAt": null, "revokedAt": null, "revision": "20000000-0000-4000-8000-000000000001" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "patch": { "operationId": "updateApiKeysKeyId", "summary": "Consultar/alterar metadados e restrições permitidas", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. Exige sessão humana verificada. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "api-keys" ], "parameters": [ { "name": "keyId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Revision" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "api_keys:update", "x-agilink-resource-scope": "subject_owned", "x-agilink-milestone": "A2", "x-agilink-future-oauth": "excluded", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyPatch" }, "example": { "name": "Backend renomeado" } } } }, "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyEnvelope" }, "example": { "data": { "id": "30000000-0000-4000-8000-000000000001", "name": "Backend da loja", "prefix": "agl_test_AbCdEf", "appIds": [ "app_loja" ], "permissions": [ "apps:read", "links:read", "links:create" ], "expiresAt": "2027-01-17T20:00:00Z", "createdAt": "2026-10-19T20:00:00Z", "lastUsedAt": null, "revokedAt": null, "revision": "20000000-0000-4000-8000-000000000001" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "delete": { "operationId": "deleteApiKeysKeyId", "summary": "Revogação", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. Exige sessão humana verificada. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "api-keys" ], "parameters": [ { "name": "keyId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Revision" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "api_keys:delete", "x-agilink-resource-scope": "subject_owned", "x-agilink-milestone": "A2", "x-agilink-future-oauth": "excluded", "responses": { "204": { "description": "Credencial revogada; corpo vazio.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/links": { "get": { "operationId": "getLinks", "summary": "Listar/buscar por app, domínio, grupo, estado, tags, pasta, campanha e período", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "links" ], "parameters": [ { "name": "appId", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Cursor" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "group", "in": "query", "required": false, "schema": { "enum": [ "main", "operational" ] } }, { "name": "domain", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Domain" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "createdAt:desc", "createdAt:asc" ], "default": "createdAt:desc" } }, { "name": "prefix", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "origin", "in": "query", "required": false, "schema": { "enum": [ "api", "dashboard" ] } }, { "name": "createdFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "createdTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "folderId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "campaignId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "tagId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "archived", "in": "query", "required": false, "schema": { "type": "string" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "links:read", "x-agilink-resource-scope": "query_or_body_app", "x-agilink-milestone": "A3a", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkListEnvelope" }, "example": { "data": [ { "id": "go.example.com~-ofertas~-tenis", "appId": "app_loja", "domain": "go.example.com", "prefix": "ofertas", "slug": "tenis", "url": "https://go.example.com/ofertas/tenis", "title": "Tênis da campanha", "description": null, "imageUrl": null, "desktopUrl": "https://shop.example.com/produtos/tenis", "appPath": "produtos/tenis", "parameters": {}, "webOnly": false, "behavior": "manual", "group": "operational", "origin": "api", "revision": "20000000-0000-4000-8000-000000000001", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z", "publication": { "status": "pending", "desiredRevision": "20000000-0000-4000-8000-000000000001", "confirmedRevision": null, "updatedAt": "2026-10-19T20:00:00Z" } } ], "pagination": { "nextCursor": null, "hasMore": false }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "post": { "operationId": "createLinks", "summary": "Criar link web/deep link com idempotência", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "links" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "links:create", "x-agilink-resource-scope": "query_or_body_app", "x-agilink-milestone": "A3a", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkCreate" }, "example": { "appId": "app_loja", "domain": "go.example.com", "prefix": "ofertas", "slug": "tenis", "title": "Tênis da campanha", "desktopUrl": "https://shop.example.com/produtos/tenis", "appPath": "produtos/tenis" } } } }, "responses": { "201": { "description": "Criado. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" }, "Location": { "description": "Endereço relativo do recurso criado.", "schema": { "type": "string" }, "example": "/v1/links/go.example.com~-ofertas~-tenis" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkEnvelope" }, "example": { "data": { "id": "go.example.com~-ofertas~-tenis", "appId": "app_loja", "domain": "go.example.com", "prefix": "ofertas", "slug": "tenis", "url": "https://go.example.com/ofertas/tenis", "title": "Tênis da campanha", "description": null, "imageUrl": null, "desktopUrl": "https://shop.example.com/produtos/tenis", "appPath": "produtos/tenis", "parameters": {}, "webOnly": false, "behavior": "manual", "group": "operational", "origin": "api", "revision": "20000000-0000-4000-8000-000000000001", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z", "publication": { "status": "pending", "desiredRevision": "20000000-0000-4000-8000-000000000001", "confirmedRevision": null, "updatedAt": "2026-10-19T20:00:00Z" } }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/links/{linkId}": { "get": { "operationId": "getLinksLinkId", "summary": "Consultar contrato administrativo e revisão", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "links" ], "parameters": [ { "name": "linkId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/LinkId" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "links:read", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3a", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkEnvelope" }, "example": { "data": { "id": "go.example.com~-ofertas~-tenis", "appId": "app_loja", "domain": "go.example.com", "prefix": "ofertas", "slug": "tenis", "url": "https://go.example.com/ofertas/tenis", "title": "Tênis da campanha", "description": null, "imageUrl": null, "desktopUrl": "https://shop.example.com/produtos/tenis", "appPath": "produtos/tenis", "parameters": {}, "webOnly": false, "behavior": "manual", "group": "operational", "origin": "api", "revision": "20000000-0000-4000-8000-000000000001", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z", "publication": { "status": "pending", "desiredRevision": "20000000-0000-4000-8000-000000000001", "confirmedRevision": null, "updatedAt": "2026-10-19T20:00:00Z" } }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "patch": { "operationId": "updateLinksLinkId", "summary": "Atualizar campos mutáveis com revisão", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "links" ], "parameters": [ { "name": "linkId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/LinkId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "links:update", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3a", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkPatch" }, "example": { "title": "Tênis em promoção" } } } }, "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkEnvelope" }, "example": { "data": { "id": "go.example.com~-ofertas~-tenis", "appId": "app_loja", "domain": "go.example.com", "prefix": "ofertas", "slug": "tenis", "url": "https://go.example.com/ofertas/tenis", "title": "Tênis da campanha", "description": null, "imageUrl": null, "desktopUrl": "https://shop.example.com/produtos/tenis", "appPath": "produtos/tenis", "parameters": {}, "webOnly": false, "behavior": "manual", "group": "operational", "origin": "api", "revision": "20000000-0000-4000-8000-000000000001", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z", "publication": { "status": "pending", "desiredRevision": "20000000-0000-4000-8000-000000000001", "confirmedRevision": null, "updatedAt": "2026-10-19T20:00:00Z" } }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "delete": { "operationId": "deleteLinksLinkId", "summary": "Exclusão autorizada com revisão e dependências", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "links" ], "parameters": [ { "name": "linkId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/LinkId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "links:delete", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3a", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "204": { "description": "Removido. Corpo vazio; publicação da remoção acompanha outbox.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/operations/{operationId}": { "get": { "operationId": "getOperationsOperationId", "summary": "Consultar operação com autorização do recurso original", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "operations" ], "parameters": [ { "name": "operationId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "operations:read", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A2", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationEnvelope" }, "example": { "data": { "id": "op_example", "appId": "app_loja", "type": "link.resync", "status": "queued", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z", "revision": "20000000-0000-4000-8000-000000000001", "result": null, "error": null }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/api-keys/{keyId}/rotate": { "post": { "operationId": "rotateApiKeysKeyId", "summary": "Rotação com política explícita de sobreposição", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. Exige sessão humana verificada. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "api-keys" ], "parameters": [ { "name": "keyId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Revision" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "api_keys:rotate", "x-agilink-resource-scope": "subject_owned", "x-agilink-milestone": "A2", "x-agilink-future-oauth": "excluded", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyRotate" }, "example": { "overlapSeconds": 0 } } } }, "responses": { "201": { "description": "Criado. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" }, "Location": { "description": "Endereço relativo do recurso criado.", "schema": { "type": "string" }, "example": "/v1/api-keys/{keyId}/rotate/30000000-0000-4000-8000-000000000001" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyIssuedEnvelope" }, "example": { "data": { "key": { "id": "30000000-0000-4000-8000-000000000001", "name": "Backend da loja", "prefix": "agl_test_AbCdEf", "appIds": [ "app_loja" ], "permissions": [ "apps:read", "links:read", "links:create" ], "expiresAt": "2027-01-17T20:00:00Z", "createdAt": "2026-10-19T20:00:00Z", "lastUsedAt": null, "revokedAt": null, "revision": "20000000-0000-4000-8000-000000000001" }, "secret": "agl_test_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/capabilities": { "get": { "operationId": "getCapabilities", "summary": "Operações habilitadas e limites visíveis ao principal", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "capabilities" ], "parameters": [], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "capabilities:read", "x-agilink-resource-scope": "principal", "x-agilink-milestone": "A2", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilitiesEnvelope" }, "example": { "data": { "environment": "staging", "operations": [ { "operationId": "getMe", "permission": "identity:read" } ], "oauth": false, "mcp": false }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/apps/{appId}/capabilities": { "get": { "operationId": "getAppsAppIdCapabilities", "summary": "Habilitações e restrições efetivas", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "apps" ], "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "capabilities:read", "x-agilink-resource-scope": "path_app", "x-agilink-milestone": "A2", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilitiesEnvelope" }, "example": { "data": { "environment": "staging", "operations": [ { "operationId": "getMe", "permission": "identity:read" } ], "oauth": false, "mcp": false }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/apps/{appId}/usage": { "get": { "operationId": "getAppsAppIdUsage", "summary": "Uso, quotas técnicas e limites por categoria", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "apps" ], "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "usage:read", "x-agilink-resource-scope": "path_app", "x-agilink-milestone": "A2", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageEnvelope" }, "example": { "data": { "appId": "app_loja", "scope": "credential", "windowSeconds": 60, "limits": { "ingress": 1200, "read": 600, "write": 120 }, "usage": { "read": 1 }, "sharedLimits": { "owner": { "ingress": 2400, "read": 1200, "write": 240 }, "app": { "ingress": 1200, "read": 600, "write": 120 } }, "sharedUsage": { "owner": { "read": 1 }, "app": { "read": 1 } } }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/audit-events": { "get": { "operationId": "getAuditEvents", "summary": "Atividade de conta filtrada ao proprietário", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. Exige sessão humana verificada. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "audit-events" ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Cursor" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "security": [ { "HumanSession": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "audit_events:read", "x-agilink-resource-scope": "subject_owned", "x-agilink-milestone": "A2", "x-agilink-future-oauth": "excluded", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditEventListEnvelope" }, "example": { "data": [], "pagination": { "nextCursor": null, "hasMore": false }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/requests": { "get": { "operationId": "getRequests", "summary": "Diagnóstico sanitizado das requisições da conta", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. Exige sessão humana verificada. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "requests" ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Cursor" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "security": [ { "HumanSession": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "requests:read", "x-agilink-resource-scope": "subject_owned", "x-agilink-milestone": "A2", "x-agilink-future-oauth": "excluded", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestListEnvelope" }, "example": { "data": [], "pagination": { "nextCursor": null, "hasMore": false }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/operations/{operationId}/cancel": { "post": { "operationId": "cancelOperationsOperationId", "summary": "Cancelar trabalho pendente quando suportado", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "operations" ], "parameters": [ { "name": "operationId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "operations:cancel", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A2", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyObject" }, "example": {} } } }, "responses": { "202": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" }, "Location": { "description": "Operação a acompanhar.", "schema": { "type": "string" }, "example": "/v1/operations/op_example" }, "Retry-After": { "description": "Segundos até a próxima consulta.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationEnvelope" }, "example": { "data": { "id": "op_example", "appId": "app_loja", "type": "link.resync", "status": "queued", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z", "revision": "20000000-0000-4000-8000-000000000001", "result": null, "error": null }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/apps": { "get": { "operationId": "getApps", "summary": "Apps visíveis à credencial, com paginação", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "apps" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Cursor" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "apps:read", "x-agilink-resource-scope": "allowed_apps", "x-agilink-milestone": "A3a", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppListEnvelope" }, "example": { "data": [ { "id": "app_loja", "name": "Loja", "defaultDomain": "go.example.com", "desktopUrl": "https://shop.example.com/", "playStoreUrl": null, "appStoreUrl": null, "scheme": "loja", "androidPackage": "com.example.loja", "iosBundleId": "com.example.loja", "revision": "20000000-0000-4000-8000-000000000001", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z" } ], "pagination": { "hasMore": false, "nextCursor": null }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "post": { "operationId": "createApps", "summary": "Criar aplicativo com configurações iniciais", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. Exige sessão humana verificada. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "apps" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." } ], "security": [ { "HumanSession": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "apps:create", "x-agilink-resource-scope": "subject_owned", "x-agilink-milestone": "A3a", "x-agilink-future-oauth": "excluded", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppCreate" }, "example": { "name": "Loja", "desktopUrl": "https://shop.example.com/", "scheme": "loja", "androidPackage": "com.example.loja", "iosBundleId": "com.example.loja" } } } }, "responses": { "201": { "description": "Criado. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" }, "Location": { "description": "Endereço relativo do recurso criado.", "schema": { "type": "string" }, "example": "/v1/apps/30000000-0000-4000-8000-000000000001" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppEnvelope" }, "example": { "data": { "id": "app_loja", "name": "Loja", "defaultDomain": "go.example.com", "desktopUrl": "https://shop.example.com/", "playStoreUrl": null, "appStoreUrl": null, "scheme": "loja", "androidPackage": "com.example.loja", "iosBundleId": "com.example.loja", "revision": "20000000-0000-4000-8000-000000000001", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/apps/{appId}": { "get": { "operationId": "getAppsAppId", "summary": "Consultar cadastro e configuração", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "apps" ], "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "apps:read", "x-agilink-resource-scope": "path_app", "x-agilink-milestone": "A3a", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppEnvelope" }, "example": { "data": { "id": "app_loja", "name": "Loja", "defaultDomain": "go.example.com", "desktopUrl": "https://shop.example.com/", "playStoreUrl": null, "appStoreUrl": null, "scheme": "loja", "androidPackage": "com.example.loja", "iosBundleId": "com.example.loja", "revision": "20000000-0000-4000-8000-000000000001", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "patch": { "operationId": "updateAppsAppId", "summary": "Atualizar nome, destinos e campos permitidos", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "apps" ], "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "apps:update", "x-agilink-resource-scope": "path_app", "x-agilink-milestone": "A3a", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppPatch" }, "example": { "name": "Loja nova" } } } }, "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppEnvelope" }, "example": { "data": { "id": "app_loja", "name": "Loja", "defaultDomain": "go.example.com", "desktopUrl": "https://shop.example.com/", "playStoreUrl": null, "appStoreUrl": null, "scheme": "loja", "androidPackage": "com.example.loja", "iosBundleId": "com.example.loja", "revision": "20000000-0000-4000-8000-000000000001", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "delete": { "operationId": "deleteAppsAppId", "summary": "Excluir respeitando links, domínios, templates e histórico", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "apps" ], "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "apps:delete", "x-agilink-resource-scope": "path_app", "x-agilink-milestone": "A3a", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "204": { "description": "Aplicativo sem dependências excluído; tokens legados revogados. Corpo vazio.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/apps/{appId}/defaults": { "get": { "operationId": "getAppsAppIdDefaults", "summary": "Padrões de domínio, destinos e apresentação", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "apps" ], "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "apps:read", "x-agilink-resource-scope": "path_app", "x-agilink-milestone": "A3a", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppDefaultsEnvelope" }, "example": { "data": { "appId": "app_loja", "domain": "go.example.com", "desktopUrl": "https://shop.example.com/", "playStoreUrl": null, "appStoreUrl": null, "revision": "20000000-0000-4000-8000-000000000001" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "put": { "operationId": "setAppsAppIdDefaults", "summary": "Padrões de domínio, destinos e apresentação", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "apps" ], "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "apps:update", "x-agilink-resource-scope": "path_app", "x-agilink-milestone": "A3a", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppDefaultsPut" }, "example": { "domain": "go.example.com", "desktopUrl": "https://shop.example.com/", "playStoreUrl": null, "appStoreUrl": null } } } }, "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppDefaultsEnvelope" }, "example": { "data": { "appId": "app_loja", "domain": "go.example.com", "desktopUrl": "https://shop.example.com/", "playStoreUrl": null, "appStoreUrl": null, "revision": "20000000-0000-4000-8000-000000000001" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/apps/{appId}/logo": { "get": { "operationId": "getAppsAppIdLogo", "summary": "Consultar, associar e remover logo via ativo autorizado", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "apps" ], "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "apps:read", "x-agilink-resource-scope": "path_app", "x-agilink-milestone": "A3a", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppLogoEnvelope" }, "example": { "data": { "appId": "app_loja", "asset": { "id": "50000000-0000-4000-8000-000000000001", "appId": "app_loja", "url": "https://images.staging.agilink.io/40000000-0000-4000-8000-000000000001/app_loja/50000000-0000-4000-8000-000000000001.png", "state": "active", "revision": "20000000-0000-4000-8000-000000000001", "contentType": "image/png", "byteSize": 68, "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z" }, "revision": "20000000-0000-4000-8000-000000000001" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "put": { "operationId": "setAppsAppIdLogo", "summary": "Consultar, associar e remover logo via ativo autorizado", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "apps" ], "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "apps:update", "x-agilink-resource-scope": "path_app", "x-agilink-milestone": "A3a", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppLogoPut" }, "example": { "assetId": "50000000-0000-4000-8000-000000000001" } } } }, "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppLogoEnvelope" }, "example": { "data": { "appId": "app_loja", "asset": { "id": "50000000-0000-4000-8000-000000000001", "appId": "app_loja", "url": "https://images.staging.agilink.io/40000000-0000-4000-8000-000000000001/app_loja/50000000-0000-4000-8000-000000000001.png", "state": "active", "revision": "20000000-0000-4000-8000-000000000001", "contentType": "image/png", "byteSize": 68, "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z" }, "revision": "20000000-0000-4000-8000-000000000001" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "delete": { "operationId": "deleteAppsAppIdLogo", "summary": "Consultar, associar e remover logo via ativo autorizado", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "apps" ], "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "apps:update", "x-agilink-resource-scope": "path_app", "x-agilink-milestone": "A3a", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "204": { "description": "Logo padrão desvinculado; arquivo preservado. Corpo vazio.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/links/{linkId}/duplicate": { "post": { "operationId": "duplicateLinksLinkId", "summary": "Criar novo link a partir de configuração existente", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "links" ], "parameters": [ { "name": "linkId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/LinkId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "links:create", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3a", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkDuplicate" }, "example": { "slug": "tenis-copia" } } } }, "responses": { "201": { "description": "Criado. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" }, "Location": { "description": "Endereço relativo do recurso criado.", "schema": { "type": "string" }, "example": "/v1/links/{linkId}/duplicate/30000000-0000-4000-8000-000000000001" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkEnvelope" }, "example": { "data": { "id": "go.example.com~-ofertas~-tenis", "appId": "app_loja", "domain": "go.example.com", "prefix": "ofertas", "slug": "tenis", "url": "https://go.example.com/ofertas/tenis", "title": "Tênis da campanha", "description": null, "imageUrl": null, "desktopUrl": "https://shop.example.com/produtos/tenis", "appPath": "produtos/tenis", "parameters": {}, "webOnly": false, "behavior": "manual", "group": "operational", "origin": "api", "revision": "20000000-0000-4000-8000-000000000001", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z", "publication": { "status": "pending", "desiredRevision": "20000000-0000-4000-8000-000000000001", "confirmedRevision": null, "updatedAt": "2026-10-19T20:00:00Z" } }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/links/validate": { "post": { "operationId": "validateLinks", "summary": "Validar entrada e indicar conflitos conhecidos sem reservar endereço", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "links" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "links:validate", "x-agilink-resource-scope": "query_or_body_app", "x-agilink-milestone": "A3a", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkCreate" }, "example": { "appId": "app_loja", "domain": "go.example.com", "prefix": "ofertas", "slug": "tenis", "title": "Tênis da campanha", "desktopUrl": "https://shop.example.com/produtos/tenis", "appPath": "produtos/tenis" } } } }, "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkValidationEnvelope" }, "example": { "data": { "valid": true, "available": true, "normalized": { "appId": "app_loja", "domain": "go.example.com", "prefix": "ofertas", "slug": "tenis", "title": "Tênis", "desktopUrl": "https://shop.example.com/" } }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/links/availability": { "get": { "operationId": "getLinksAvailability", "summary": "Consultar disponibilidade de domínio/prefixo/slug autorizado", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "links" ], "parameters": [ { "name": "appId", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AppId" } }, { "name": "domain", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/Domain" } }, { "name": "prefix", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "slug", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 200 } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "links:read", "x-agilink-resource-scope": "query_or_body_app", "x-agilink-milestone": "A3a", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkAvailabilityEnvelope" }, "example": { "data": { "appId": "app_loja", "domain": "go.example.com", "prefix": "ofertas", "slug": "tenis", "available": true }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/links/{linkId}/preview": { "post": { "operationId": "previewLinksLinkId", "summary": "Simular destino por cenário sem gerar clique nem fazer redirect", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "links" ], "parameters": [ { "name": "linkId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/LinkId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "links:preview", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3a", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkPreview" }, "example": { "platform": "android", "source": "browser" } } } }, "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkPreviewResultEnvelope" }, "example": { "data": { "state": "active", "allowed": true, "matchedRuleId": null, "evaluatedAt": "2026-10-19T20:00:00Z", "linkId": "go.example.com~-ofertas~-tenis", "appId": "app_loja", "platform": "android", "mode": "android", "nativeUrl": "loja://produtos/tenis", "fallbackUrl": "https://shop.example.com/", "opening": "manual", "publication": { "status": "pending", "desiredRevision": "20000000-0000-4000-8000-000000000001", "confirmedRevision": null, "updatedAt": "2026-10-19T20:00:00Z" }, "sideEffects": false }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/links/{linkId}/publication": { "get": { "operationId": "getLinksLinkIdPublication", "summary": "Consultar revisão desejada/confirmada e estado de sincronização", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "links" ], "parameters": [ { "name": "linkId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/LinkId" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "links:read", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3a", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkPublicationEnvelope" }, "example": { "data": { "linkId": "go.example.com~-ofertas~-tenis", "appId": "app_loja", "revision": "20000000-0000-4000-8000-000000000001", "status": "pending", "desiredRevision": "20000000-0000-4000-8000-000000000001", "confirmedRevision": null, "updatedAt": "2026-10-19T20:00:00Z" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/links/{linkId}/resync": { "post": { "operationId": "resyncLinksLinkId", "summary": "Solicitar ressincronização via outbox", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "links" ], "parameters": [ { "name": "linkId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/LinkId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "links:resync", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3a", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyObject" }, "example": {} } } }, "responses": { "202": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" }, "Location": { "description": "Estado de propagação do link.", "schema": { "type": "string" }, "example": "/v1/links/go.example.com~-ofertas~-tenis/publication" }, "Retry-After": { "description": "Segundos até a próxima consulta.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkPublicationEnvelope" }, "example": { "data": { "linkId": "go.example.com~-ofertas~-tenis", "appId": "app_loja", "revision": "20000000-0000-4000-8000-000000000001", "status": "pending", "desiredRevision": "20000000-0000-4000-8000-000000000001", "confirmedRevision": null, "updatedAt": "2026-10-19T20:00:00Z" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/assets": { "get": { "operationId": "getAssets", "summary": "Listar e fazer upload de ativos autorizados", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "assets" ], "parameters": [ { "name": "appId", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AppId" } }, { "name": "state", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/AssetStateFilter" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Cursor" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "assets:read", "x-agilink-resource-scope": "query_or_body_app", "x-agilink-milestone": "A3a", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetListEnvelope" }, "example": { "data": [ { "id": "50000000-0000-4000-8000-000000000001", "appId": "app_loja", "url": "https://images.staging.agilink.io/40000000-0000-4000-8000-000000000001/app_loja/50000000-0000-4000-8000-000000000001.png", "state": "active", "revision": "20000000-0000-4000-8000-000000000001", "contentType": "image/png", "byteSize": 68, "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z" } ], "pagination": { "hasMore": false, "nextCursor": null }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "post": { "operationId": "createAssets", "summary": "Listar e fazer upload de ativos autorizados", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "assets" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "assets:create", "x-agilink-resource-scope": "query_or_body_app", "x-agilink-milestone": "A3a", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/AssetUploadForm" }, "example": { "appId": "app_loja", "file": "" }, "encoding": { "file": { "contentType": "image/png, image/jpeg" } } } } }, "responses": { "201": { "description": "Criado. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" }, "Location": { "description": "Endereço relativo do recurso criado.", "schema": { "type": "string" }, "example": "/v1/assets/30000000-0000-4000-8000-000000000001" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetEnvelope" }, "example": { "data": { "id": "50000000-0000-4000-8000-000000000001", "appId": "app_loja", "url": "https://images.staging.agilink.io/40000000-0000-4000-8000-000000000001/app_loja/50000000-0000-4000-8000-000000000001.png", "state": "active", "revision": "20000000-0000-4000-8000-000000000001", "contentType": "image/png", "byteSize": 68, "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/assets/{assetId}": { "get": { "operationId": "getAssetsAssetId", "summary": "Metadados e exclusão condicionada a referências", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "assets" ], "parameters": [ { "name": "assetId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "assets:read", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3a", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetEnvelope" }, "example": { "data": { "id": "50000000-0000-4000-8000-000000000001", "appId": "app_loja", "url": "https://images.staging.agilink.io/40000000-0000-4000-8000-000000000001/app_loja/50000000-0000-4000-8000-000000000001.png", "state": "active", "revision": "20000000-0000-4000-8000-000000000001", "contentType": "image/png", "byteSize": 68, "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "delete": { "operationId": "deleteAssetsAssetId", "summary": "Metadados e exclusão condicionada a referências", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "assets" ], "parameters": [ { "name": "assetId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "assets:delete", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3a", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "204": { "description": "Bytes removidos do R2 e ativo marcado como deleted. Corpo vazio.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/domains": { "get": { "operationId": "getDomains", "summary": "Listar domínios autorizados e estados", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "domains" ], "parameters": [ { "name": "appId", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AppId" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Cursor" } }, { "name": "detached", "in": "query", "required": false, "schema": { "enum": [ "false", "true", "all" ], "default": "false" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "domains:read", "x-agilink-resource-scope": "query_or_body_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainListEnvelope" }, "example": { "data": [ { "id": "domain_loja", "appId": "app_loja", "hostname": "go.example.com", "mode": "external", "ownership": "unverified", "dns": "pending", "https": "pending", "links": "pending", "detached": false, "removalState": null, "canManageDns": false, "zoneName": "example.com", "nameservers": [], "challenge": null, "connectionRecords": [], "nativeConfig": {}, "revision": "20000000-0000-4000-8000-000000000001", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z", "publication": { "status": "pending", "desiredRevision": "20000000-0000-4000-8000-000000000001", "confirmedRevision": null, "updatedAt": "2026-10-19T20:00:00Z" }, "lastCheckedAt": null, "lastError": null } ], "pagination": { "hasMore": false, "nextCursor": null }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "post": { "operationId": "createDomains", "summary": "Solicitar domínio de plataforma ou conectar domínio próprio", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "domains" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "domains:create", "x-agilink-resource-scope": "query_or_body_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainCreate" }, "example": { "appId": "app_loja", "mode": "platform", "prefix": "minhaloja" } } } }, "responses": { "202": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" }, "Location": { "description": "Operação a acompanhar.", "schema": { "type": "string" }, "example": "/v1/operations/op_example" }, "Retry-After": { "description": "Segundos até a próxima consulta.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationEnvelope" }, "example": { "data": { "id": "op_example", "appId": "app_loja", "type": "link.resync", "status": "queued", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z", "revision": "20000000-0000-4000-8000-000000000001", "result": null, "error": null }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/domains/{domainId}": { "get": { "operationId": "getDomainsDomainId", "summary": "Detalhe, instruções e pendências", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "domains" ], "parameters": [ { "name": "domainId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "domains:read", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainEnvelope" }, "example": { "data": { "id": "domain_loja", "appId": "app_loja", "hostname": "go.example.com", "mode": "external", "ownership": "unverified", "dns": "pending", "https": "pending", "links": "pending", "detached": false, "removalState": null, "canManageDns": false, "zoneName": "example.com", "nameservers": [], "challenge": null, "connectionRecords": [], "nativeConfig": {}, "revision": "20000000-0000-4000-8000-000000000001", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z", "publication": { "status": "pending", "desiredRevision": "20000000-0000-4000-8000-000000000001", "confirmedRevision": null, "updatedAt": "2026-10-19T20:00:00Z" }, "lastCheckedAt": null, "lastError": null }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "delete": { "operationId": "deleteDomainsDomainId", "summary": "Desvincular com dependências e operação recuperável", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "domains" ], "parameters": [ { "name": "domainId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "domains:delete", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "202": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" }, "Location": { "description": "Operação a acompanhar.", "schema": { "type": "string" }, "example": "/v1/operations/op_example" }, "Retry-After": { "description": "Segundos até a próxima consulta.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationEnvelope" }, "example": { "data": { "id": "op_example", "appId": "app_loja", "type": "link.resync", "status": "queued", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z", "revision": "20000000-0000-4000-8000-000000000001", "result": null, "error": null }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/domains/{domainId}/capabilities": { "get": { "operationId": "getDomainsDomainIdCapabilities", "summary": "Ações possíveis para aquele modo e usuário", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "domains" ], "parameters": [ { "name": "domainId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "capabilities:read", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainCapabilitiesEnvelope" }, "example": { "data": { "domainId": "domain_loja", "appId": "app_loja", "revision": "20000000-0000-4000-8000-000000000001", "mode": "external", "actions": { "verify": true, "detach": true, "dns": false, "nativeConfig": false, "webConfig": false, "recovery": false, "templates": true }, "reasons": { "dns": "DNS externo permanece no seu provedor." } }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/domains/{domainId}/verify": { "post": { "operationId": "verifyDomainsDomainId", "summary": "Verificar propriedade, DNS, TLS e prontidão", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "domains" ], "parameters": [ { "name": "domainId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "domains:verify", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyObject" }, "example": {} } } }, "responses": { "202": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" }, "Location": { "description": "Operação a acompanhar.", "schema": { "type": "string" }, "example": "/v1/operations/op_example" }, "Retry-After": { "description": "Segundos até a próxima consulta.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationEnvelope" }, "example": { "data": { "id": "op_example", "appId": "app_loja", "type": "link.resync", "status": "queued", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z", "revision": "20000000-0000-4000-8000-000000000001", "result": null, "error": null }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/domains/{domainId}/native-config": { "get": { "operationId": "getDomainsDomainIdNativeConfig", "summary": "Configuração Android, iOS, scheme e rotas", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "domains" ], "parameters": [ { "name": "domainId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "native_config:read", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainConfigEnvelope" }, "example": { "data": { "domainId": "domain_loja", "appId": "app_loja", "revision": "20000000-0000-4000-8000-000000000001", "config": {}, "publication": { "status": "pending", "desiredRevision": "20000000-0000-4000-8000-000000000001", "confirmedRevision": null, "updatedAt": "2026-10-19T20:00:00Z" } }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "put": { "operationId": "setDomainsDomainIdNativeConfig", "summary": "Configuração Android, iOS, scheme e rotas", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "domains" ], "parameters": [ { "name": "domainId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "native_config:update", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeConfigPut" }, "example": { "androidPackage": "com.example.loja", "fingerprints": [ "AA:AA:AA:AA:AA:AA:AA:AA:AA:AA:AA:AA:AA:AA:AA:AA:AA:AA:AA:AA:AA:AA:AA:AA:AA:AA:AA:AA:AA:AA:AA:AA" ] } } } }, "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainConfigEnvelope" }, "example": { "data": { "domainId": "domain_loja", "appId": "app_loja", "revision": "20000000-0000-4000-8000-000000000001", "config": {}, "publication": { "status": "pending", "desiredRevision": "20000000-0000-4000-8000-000000000001", "confirmedRevision": null, "updatedAt": "2026-10-19T20:00:00Z" } }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/domains/{domainId}/web-config": { "get": { "operationId": "getDomainsDomainIdWebConfig", "summary": "Destino web, metadados e prefixo", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "domains" ], "parameters": [ { "name": "domainId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "web_config:read", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainConfigEnvelope" }, "example": { "data": { "domainId": "domain_loja", "appId": "app_loja", "revision": "20000000-0000-4000-8000-000000000001", "config": {}, "publication": { "status": "pending", "desiredRevision": "20000000-0000-4000-8000-000000000001", "confirmedRevision": null, "updatedAt": "2026-10-19T20:00:00Z" } }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "put": { "operationId": "setDomainsDomainIdWebConfig", "summary": "Destino web, metadados e prefixo", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "domains" ], "parameters": [ { "name": "domainId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "web_config:update", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebConfigPut" }, "example": { "flutterUrl": "https://shop.example.com", "flutterRoutePrefix": "/produtos/", "flutterName": "Loja" } } } }, "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainConfigEnvelope" }, "example": { "data": { "domainId": "domain_loja", "appId": "app_loja", "revision": "20000000-0000-4000-8000-000000000001", "config": {}, "publication": { "status": "pending", "desiredRevision": "20000000-0000-4000-8000-000000000001", "confirmedRevision": null, "updatedAt": "2026-10-19T20:00:00Z" } }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/domains/{domainId}/recovery-config": { "get": { "operationId": "getDomainsDomainIdRecoveryConfig", "summary": "Opções de recuperação disponíveis", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "domains" ], "parameters": [ { "name": "domainId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "recovery_config:read", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainConfigEnvelope" }, "example": { "data": { "domainId": "domain_loja", "appId": "app_loja", "revision": "20000000-0000-4000-8000-000000000001", "config": {}, "publication": { "status": "pending", "desiredRevision": "20000000-0000-4000-8000-000000000001", "confirmedRevision": null, "updatedAt": "2026-10-19T20:00:00Z" } }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "put": { "operationId": "setDomainsDomainIdRecoveryConfig", "summary": "Opções de recuperação disponíveis", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "domains" ], "parameters": [ { "name": "domainId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "recovery_config:update", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryConfigPut" }, "example": { "enabled": false, "sdkReady": false } } } }, "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainConfigEnvelope" }, "example": { "data": { "domainId": "domain_loja", "appId": "app_loja", "revision": "20000000-0000-4000-8000-000000000001", "config": {}, "publication": { "status": "pending", "desiredRevision": "20000000-0000-4000-8000-000000000001", "confirmedRevision": null, "updatedAt": "2026-10-19T20:00:00Z" } }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/domains/{domainId}/diagnostics": { "get": { "operationId": "getDomainsDomainIdDiagnostics", "summary": "Diagnóstico estruturado das associações e publicação", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "domains" ], "parameters": [ { "name": "domainId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "domains:read", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainDiagnosticsEnvelope" }, "example": { "data": { "domainId": "domain_loja", "appId": "app_loja", "revision": "20000000-0000-4000-8000-000000000001", "configurationSaved": true, "publication": { "status": "pending", "desiredRevision": "20000000-0000-4000-8000-000000000001", "confirmedRevision": null, "updatedAt": "2026-10-19T20:00:00Z" }, "ownership": "unverified", "dns": "pending", "https": "pending", "links": "pending", "androidConfigured": false, "iosConfigured": false, "deviceAssociationTested": false, "appClipVerified": false, "notes": [ "Configuração salva não prova associação em aparelho." ] }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/domain-options": { "get": { "operationId": "getDomainOptions", "summary": "Opções de plataforma e orientações suportadas de domínio raiz", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "domain-options" ], "parameters": [ { "name": "appId", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AppId" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "domains:read", "x-agilink-resource-scope": "query_or_body_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainOptionsEnvelope" }, "example": { "data": { "appId": "app_loja", "enabled": true, "mutationsEnabled": true, "platformDomain": "links.staging.agilink.io", "modes": [ "platform" ], "externalDns": { "enabled": false, "apexProfiles": [] } }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/domains/{domainId}/dns-records": { "get": { "operationId": "getDomainsDomainIdDnsRecords", "summary": "Listar registros administráveis", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "domains" ], "parameters": [ { "name": "domainId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Cursor" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "dns:read", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DnsRecordListEnvelope" }, "example": { "data": [ { "id": "record_example", "name": "_example.go.example.com", "type": "TXT", "content": "example", "ttl": 300, "proxied": false, "priority": null, "version": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "revision": "20000000-0000-4000-8000-000000000001", "canEdit": true, "canDelete": true, "protectedReason": null } ], "pagination": { "hasMore": false, "nextCursor": null }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "post": { "operationId": "createDomainsDomainIdDnsRecords", "summary": "Criar registro permitido", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "domains" ], "parameters": [ { "name": "domainId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "dns:create", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DnsRecordInput" }, "example": { "type": "TXT", "name": "_example.go.example.com", "content": "example", "ttl": 300, "proxied": false } } } }, "responses": { "202": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" }, "Location": { "description": "Operação a acompanhar.", "schema": { "type": "string" }, "example": "/v1/operations/op_example" }, "Retry-After": { "description": "Segundos até a próxima consulta.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationEnvelope" }, "example": { "data": { "id": "op_example", "appId": "app_loja", "type": "link.resync", "status": "queued", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z", "revision": "20000000-0000-4000-8000-000000000001", "result": null, "error": null }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/domains/{domainId}/dns-records/{recordId}": { "patch": { "operationId": "updateDomainsDomainIdDnsRecordsRecordId", "summary": "Alterar/remover registro permitido", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "domains" ], "parameters": [ { "name": "domainId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "recordId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "dns:update", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DnsRecordInput" }, "example": { "type": "TXT", "name": "_example.go.example.com", "content": "example", "ttl": 300, "proxied": false } } } }, "responses": { "202": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" }, "Location": { "description": "Operação a acompanhar.", "schema": { "type": "string" }, "example": "/v1/operations/op_example" }, "Retry-After": { "description": "Segundos até a próxima consulta.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationEnvelope" }, "example": { "data": { "id": "op_example", "appId": "app_loja", "type": "link.resync", "status": "queued", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z", "revision": "20000000-0000-4000-8000-000000000001", "result": null, "error": null }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "delete": { "operationId": "deleteDomainsDomainIdDnsRecordsRecordId", "summary": "Alterar/remover registro permitido", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "domains" ], "parameters": [ { "name": "domainId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "recordId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "dns:delete", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "202": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" }, "Location": { "description": "Operação a acompanhar.", "schema": { "type": "string" }, "example": "/v1/operations/op_example" }, "Retry-After": { "description": "Segundos até a próxima consulta.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationEnvelope" }, "example": { "data": { "id": "op_example", "appId": "app_loja", "type": "link.resync", "status": "queued", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z", "revision": "20000000-0000-4000-8000-000000000001", "result": null, "error": null }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/apps/{appId}/template-defaults": { "get": { "operationId": "getAppsAppIdTemplateDefaults", "summary": "Padrões por app", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "apps" ], "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "template_bindings:read", "x-agilink-resource-scope": "path_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateBindingViewEnvelope" }, "example": { "data": { "appId": "app_loja", "scope": "app", "revision": "20000000-0000-4000-8000-000000000001", "enabled": true, "current": { "android": { "mode": "inherit" }, "ios": { "mode": "inherit" }, "recovery": { "mode": "inherit" } }, "effective": { "android": { "mode": "inherit" }, "ios": { "mode": "inherit" }, "recovery": { "mode": "inherit" } }, "inherited": { "android": { "mode": "inherit" }, "ios": { "mode": "inherit" }, "recovery": { "mode": "inherit" } }, "templateData": {} }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "put": { "operationId": "setAppsAppIdTemplateDefaults", "summary": "Padrões por app", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "apps" ], "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "template_bindings:update", "x-agilink-resource-scope": "path_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateBindingPut" }, "example": { "baseTemplateId": "android", "choice": { "mode": "official" } } } } }, "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateBindingViewEnvelope" }, "example": { "data": { "appId": "app_loja", "scope": "app", "revision": "20000000-0000-4000-8000-000000000001", "enabled": true, "current": { "android": { "mode": "inherit" }, "ios": { "mode": "inherit" }, "recovery": { "mode": "inherit" } }, "effective": { "android": { "mode": "inherit" }, "ios": { "mode": "inherit" }, "recovery": { "mode": "inherit" } }, "inherited": { "android": { "mode": "inherit" }, "ios": { "mode": "inherit" }, "recovery": { "mode": "inherit" } }, "templateData": {} }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/domains/{domainId}/template-defaults": { "get": { "operationId": "getDomainsDomainIdTemplateDefaults", "summary": "Padrões de templates por plataforma", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "domains" ], "parameters": [ { "name": "domainId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "template_bindings:read", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateBindingViewEnvelope" }, "example": { "data": { "appId": "app_loja", "scope": "app", "revision": "20000000-0000-4000-8000-000000000001", "enabled": true, "current": { "android": { "mode": "inherit" }, "ios": { "mode": "inherit" }, "recovery": { "mode": "inherit" } }, "effective": { "android": { "mode": "inherit" }, "ios": { "mode": "inherit" }, "recovery": { "mode": "inherit" } }, "inherited": { "android": { "mode": "inherit" }, "ios": { "mode": "inherit" }, "recovery": { "mode": "inherit" } }, "templateData": {} }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "put": { "operationId": "setDomainsDomainIdTemplateDefaults", "summary": "Padrões de templates por plataforma", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "domains" ], "parameters": [ { "name": "domainId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "template_bindings:update", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateBindingPut" }, "example": { "baseTemplateId": "android", "choice": { "mode": "official" } } } } }, "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateBindingViewEnvelope" }, "example": { "data": { "appId": "app_loja", "scope": "app", "revision": "20000000-0000-4000-8000-000000000001", "enabled": true, "current": { "android": { "mode": "inherit" }, "ios": { "mode": "inherit" }, "recovery": { "mode": "inherit" } }, "effective": { "android": { "mode": "inherit" }, "ios": { "mode": "inherit" }, "recovery": { "mode": "inherit" } }, "inherited": { "android": { "mode": "inherit" }, "ios": { "mode": "inherit" }, "recovery": { "mode": "inherit" } }, "templateData": {} }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/links/{linkId}/template-selection": { "get": { "operationId": "getLinksLinkIdTemplateSelection", "summary": "Ler/alterar apresentação por plataforma", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "links" ], "parameters": [ { "name": "linkId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/LinkId" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "template_bindings:read", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateBindingViewEnvelope" }, "example": { "data": { "appId": "app_loja", "scope": "app", "revision": "20000000-0000-4000-8000-000000000001", "enabled": true, "current": { "android": { "mode": "inherit" }, "ios": { "mode": "inherit" }, "recovery": { "mode": "inherit" } }, "effective": { "android": { "mode": "inherit" }, "ios": { "mode": "inherit" }, "recovery": { "mode": "inherit" } }, "inherited": { "android": { "mode": "inherit" }, "ios": { "mode": "inherit" }, "recovery": { "mode": "inherit" } }, "templateData": {} }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "put": { "operationId": "setLinksLinkIdTemplateSelection", "summary": "Ler/alterar apresentação por plataforma", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "links" ], "parameters": [ { "name": "linkId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/LinkId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "template_bindings:update", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateBindingPut" }, "example": { "baseTemplateId": "android", "choice": { "mode": "official" } } } } }, "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateBindingViewEnvelope" }, "example": { "data": { "appId": "app_loja", "scope": "app", "revision": "20000000-0000-4000-8000-000000000001", "enabled": true, "current": { "android": { "mode": "inherit" }, "ios": { "mode": "inherit" }, "recovery": { "mode": "inherit" } }, "effective": { "android": { "mode": "inherit" }, "ios": { "mode": "inherit" }, "recovery": { "mode": "inherit" } }, "inherited": { "android": { "mode": "inherit" }, "ios": { "mode": "inherit" }, "recovery": { "mode": "inherit" } }, "templateData": {} }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/template-catalog": { "get": { "operationId": "getTemplateCatalog", "summary": "Modelos oficiais, plataformas e capacidades", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "template-catalog" ], "parameters": [ { "name": "appId", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AppId" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "templates:read", "x-agilink-resource-scope": "query_or_body_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateCatalogListEnvelope" }, "example": { "data": [ { "id": "android", "rendererContractVersion": 1, "states": [ "manual", "opening", "fallback" ], "actions": [ "open-app", "open-browser" ], "nativeVariables": [ "link.titulo", "link.descricao", "app.nome" ], "themes": { "light": { "background": "#f8fafc", "surface": "#ffffff", "border": "#e2e8f0", "text": "#0f172a", "muted": "#64748b", "accent": "#0284c7", "secondary": "#059669", "tertiary": "#f1f5f9" }, "dark": { "background": "#0c0d0e", "surface": "#141517", "border": "#26272b", "text": "#f4f4f5", "muted": "#a1a1aa", "accent": "#0284c7", "secondary": "#10b981", "tertiary": "#1c1d20" } } }, { "id": "ios", "rendererContractVersion": 1, "states": [ "opening", "fallback" ], "actions": [ "open-app", "install", "open-browser" ], "nativeVariables": [ "link.titulo", "link.descricao", "app.nome" ], "themes": { "light": { "background": "#f8fafc", "surface": "#ffffff", "border": "#e2e8f0", "text": "#0f172a", "muted": "#64748b", "accent": "#0284c7", "secondary": "#0f172a", "tertiary": "#f1f5f9" }, "dark": { "background": "#0c0d0e", "surface": "#141517", "border": "#26272b", "text": "#f4f4f5", "muted": "#a1a1aa", "accent": "#0284c7", "secondary": "#27272a", "tertiary": "#1c1d20" } } }, { "id": "recovery", "rendererContractVersion": 1, "states": [ "copy-only", "default", "copied", "manual", "fallback" ], "actions": [ "copy-install", "install", "open-app", "copy-clip" ], "nativeVariables": [ "link.titulo", "link.descricao", "app.nome" ], "themes": { "light": { "background": "#f8fafc", "surface": "#ffffff", "border": "#e2e8f0", "text": "#0f172a", "muted": "#64748b", "accent": "#0284c7", "secondary": "#059669", "tertiary": "#f1f5f9" }, "dark": { "background": "#0c0d0e", "surface": "#141517", "border": "#26272b", "text": "#f4f4f5", "muted": "#a1a1aa", "accent": "#0284c7", "secondary": "#10b981", "tertiary": "#1c1d20" } } } ], "pagination": { "hasMore": false, "nextCursor": null }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/template-catalog/{baseId}/schema": { "get": { "operationId": "getTemplateCatalogBaseIdSchema", "summary": "Campos, variáveis, tipos e restrições", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "template-catalog" ], "parameters": [ { "name": "baseId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "appId", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AppId" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "templates:read", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateSchemaResultEnvelope" }, "example": { "data": { "baseTemplateId": "android", "limits": { "configBytes": 12288, "dataBytes": 8192, "variables": 20, "details": 4 }, "schema": { "type": "object", "additionalProperties": false, "properties": { "schemaVersion": { "const": 1 }, "kind": { "const": "preset" }, "baseTemplateId": { "enum": [ "android", "ios", "recovery" ] }, "rendererContractVersion": { "const": 1 }, "appearance": { "type": "object", "additionalProperties": false, "properties": { "light": { "type": "object", "additionalProperties": false, "properties": { "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "surface": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "border": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "text": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "muted": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "accent": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "secondary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "tertiary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" } }, "required": [] }, "dark": { "type": "object", "additionalProperties": false, "properties": { "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "surface": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "border": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "text": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "muted": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "accent": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "secondary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "tertiary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" } }, "required": [] }, "fontFamily": { "enum": [ "system", "sans", "serif" ] }, "radius": { "enum": [ "small", "medium", "large" ] }, "spacing": { "enum": [ "compact", "comfortable" ] }, "logoAssetId": { "type": "string", "maxLength": 100 } }, "required": [] }, "content": { "type": "object", "additionalProperties": false, "properties": { "heading": { "type": "string", "maxLength": 120 }, "supportingText": { "type": "string", "maxLength": 1000 }, "actionLabels": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 120 } }, "details": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "label": { "type": "string", "maxLength": 80 }, "value": { "type": "string", "maxLength": 1000 } }, "required": [ "label", "value" ] }, "maxItems": 4 } }, "required": [] }, "variables": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" }, "label": { "type": "string", "maxLength": 80 }, "type": { "enum": [ "text", "number", "boolean" ] }, "required": { "type": "boolean" }, "maxLength": { "type": "integer", "minimum": 1, "maximum": 4000 }, "defaultValue": { "type": [ "string", "number", "boolean" ] } }, "required": [ "key" ] }, "maxItems": 20 } }, "required": [] }, "example": { "schemaVersion": 1, "kind": "preset", "baseTemplateId": "android", "rendererContractVersion": 1, "appearance": { "light": { "background": "#f8fafc", "surface": "#ffffff", "border": "#e2e8f0", "text": "#0f172a", "muted": "#64748b", "accent": "#0284c7", "secondary": "#059669", "tertiary": "#f1f5f9" }, "dark": { "background": "#0c0d0e", "surface": "#141517", "border": "#26272b", "text": "#f4f4f5", "muted": "#a1a1aa", "accent": "#0284c7", "secondary": "#10b981", "tertiary": "#1c1d20" }, "fontFamily": "system", "radius": "large", "spacing": "comfortable" }, "content": {}, "variables": [] } }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/template-choices": { "get": { "operationId": "getTemplateChoices", "summary": "Seleções válidas para contexto app/domínio/link", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "template-choices" ], "parameters": [ { "name": "appId", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AppId" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Cursor" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "templates:read", "x-agilink-resource-scope": "query_or_body_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateChoiceListEnvelope" }, "example": { "data": [ { "templateId": "60000000-0000-4000-8000-000000000001", "version": 1, "baseTemplateId": "android", "name": "Página da loja", "variables": [] } ], "pagination": { "hasMore": false, "nextCursor": null }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/templates": { "get": { "operationId": "getTemplates", "summary": "Biblioteca e criação por app", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "templates" ], "parameters": [ { "name": "appId", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AppId" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Cursor" } }, { "name": "archived", "in": "query", "required": false, "schema": { "enum": [ "false", "true", "all" ], "default": "false" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "templates:read", "x-agilink-resource-scope": "query_or_body_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateListEnvelope" }, "example": { "data": [ { "id": "60000000-0000-4000-8000-000000000001", "appId": "app_loja", "name": "Página da loja", "baseTemplateId": "android", "archived": false, "revision": "20000000-0000-4000-8000-000000000001", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z" } ], "pagination": { "hasMore": false, "nextCursor": null }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "post": { "operationId": "createTemplates", "summary": "Biblioteca e criação por app", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "templates" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "templates:create", "x-agilink-resource-scope": "query_or_body_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateCreate" }, "example": { "appId": "app_loja", "name": "Página da loja", "baseTemplateId": "android", "config": { "schemaVersion": 1, "kind": "preset", "baseTemplateId": "android", "rendererContractVersion": 1, "appearance": { "light": { "background": "#f8fafc", "surface": "#ffffff", "border": "#e2e8f0", "text": "#0f172a", "muted": "#64748b", "accent": "#0284c7", "secondary": "#059669", "tertiary": "#f1f5f9" }, "dark": { "background": "#0c0d0e", "surface": "#141517", "border": "#26272b", "text": "#f4f4f5", "muted": "#a1a1aa", "accent": "#0284c7", "secondary": "#10b981", "tertiary": "#1c1d20" }, "fontFamily": "system", "radius": "large", "spacing": "comfortable" }, "content": {}, "variables": [] } } } } }, "responses": { "201": { "description": "Criado. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" }, "Location": { "description": "Endereço relativo do recurso criado.", "schema": { "type": "string" }, "example": "/v1/templates/60000000-0000-4000-8000-000000000001" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateDetailEnvelope" }, "example": { "data": { "template": { "id": "60000000-0000-4000-8000-000000000001", "appId": "app_loja", "name": "Página da loja", "baseTemplateId": "android", "archived": false, "revision": "20000000-0000-4000-8000-000000000001", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z" }, "draft": { "templateId": "60000000-0000-4000-8000-000000000001", "config": { "schemaVersion": 1, "kind": "preset", "baseTemplateId": "android", "rendererContractVersion": 1, "appearance": { "light": { "background": "#f8fafc", "surface": "#ffffff", "border": "#e2e8f0", "text": "#0f172a", "muted": "#64748b", "accent": "#0284c7", "secondary": "#059669", "tertiary": "#f1f5f9" }, "dark": { "background": "#0c0d0e", "surface": "#141517", "border": "#26272b", "text": "#f4f4f5", "muted": "#a1a1aa", "accent": "#0284c7", "secondary": "#10b981", "tertiary": "#1c1d20" }, "fontFamily": "system", "radius": "large", "spacing": "comfortable" }, "content": {}, "variables": [] }, "revision": "20000000-0000-4000-8000-000000000001", "baseVersion": null, "updatedAt": "2026-10-19T20:00:00Z" }, "revision": "20000000-0000-4000-8000-000000000001" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/templates/{templateId}": { "get": { "operationId": "getTemplatesTemplateId", "summary": "Detalhe, nome e arquivamento", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "templates" ], "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "templates:read", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateDetailEnvelope" }, "example": { "data": { "template": { "id": "60000000-0000-4000-8000-000000000001", "appId": "app_loja", "name": "Página da loja", "baseTemplateId": "android", "archived": false, "revision": "20000000-0000-4000-8000-000000000001", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z" }, "draft": { "templateId": "60000000-0000-4000-8000-000000000001", "config": { "schemaVersion": 1, "kind": "preset", "baseTemplateId": "android", "rendererContractVersion": 1, "appearance": { "light": { "background": "#f8fafc", "surface": "#ffffff", "border": "#e2e8f0", "text": "#0f172a", "muted": "#64748b", "accent": "#0284c7", "secondary": "#059669", "tertiary": "#f1f5f9" }, "dark": { "background": "#0c0d0e", "surface": "#141517", "border": "#26272b", "text": "#f4f4f5", "muted": "#a1a1aa", "accent": "#0284c7", "secondary": "#10b981", "tertiary": "#1c1d20" }, "fontFamily": "system", "radius": "large", "spacing": "comfortable" }, "content": {}, "variables": [] }, "revision": "20000000-0000-4000-8000-000000000001", "baseVersion": null, "updatedAt": "2026-10-19T20:00:00Z" }, "revision": "20000000-0000-4000-8000-000000000001" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "patch": { "operationId": "updateTemplatesTemplateId", "summary": "Detalhe, nome e arquivamento", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "templates" ], "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "templates:update", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplatePatch" }, "example": { "name": "Página editada" } } } }, "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateDetailEnvelope" }, "example": { "data": { "template": { "id": "60000000-0000-4000-8000-000000000001", "appId": "app_loja", "name": "Página da loja", "baseTemplateId": "android", "archived": false, "revision": "20000000-0000-4000-8000-000000000001", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z" }, "draft": { "templateId": "60000000-0000-4000-8000-000000000001", "config": { "schemaVersion": 1, "kind": "preset", "baseTemplateId": "android", "rendererContractVersion": 1, "appearance": { "light": { "background": "#f8fafc", "surface": "#ffffff", "border": "#e2e8f0", "text": "#0f172a", "muted": "#64748b", "accent": "#0284c7", "secondary": "#059669", "tertiary": "#f1f5f9" }, "dark": { "background": "#0c0d0e", "surface": "#141517", "border": "#26272b", "text": "#f4f4f5", "muted": "#a1a1aa", "accent": "#0284c7", "secondary": "#10b981", "tertiary": "#1c1d20" }, "fontFamily": "system", "radius": "large", "spacing": "comfortable" }, "content": {}, "variables": [] }, "revision": "20000000-0000-4000-8000-000000000001", "baseVersion": null, "updatedAt": "2026-10-19T20:00:00Z" }, "revision": "20000000-0000-4000-8000-000000000001" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/templates/{templateId}/duplicate": { "post": { "operationId": "duplicateTemplatesTemplateId", "summary": "Duplicar rascunho ou versão", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "templates" ], "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "templates:create", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateDuplicate" }, "example": { "name": "Cópia", "draftRevision": "20000000-0000-4000-8000-000000000001" } } } }, "responses": { "201": { "description": "Criado. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" }, "Location": { "description": "Endereço relativo do recurso criado.", "schema": { "type": "string" }, "example": "/v1/templates/60000000-0000-4000-8000-000000000001" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateDetailEnvelope" }, "example": { "data": { "template": { "id": "60000000-0000-4000-8000-000000000001", "appId": "app_loja", "name": "Página da loja", "baseTemplateId": "android", "archived": false, "revision": "20000000-0000-4000-8000-000000000001", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z" }, "draft": { "templateId": "60000000-0000-4000-8000-000000000001", "config": { "schemaVersion": 1, "kind": "preset", "baseTemplateId": "android", "rendererContractVersion": 1, "appearance": { "light": { "background": "#f8fafc", "surface": "#ffffff", "border": "#e2e8f0", "text": "#0f172a", "muted": "#64748b", "accent": "#0284c7", "secondary": "#059669", "tertiary": "#f1f5f9" }, "dark": { "background": "#0c0d0e", "surface": "#141517", "border": "#26272b", "text": "#f4f4f5", "muted": "#a1a1aa", "accent": "#0284c7", "secondary": "#10b981", "tertiary": "#1c1d20" }, "fontFamily": "system", "radius": "large", "spacing": "comfortable" }, "content": {}, "variables": [] }, "revision": "20000000-0000-4000-8000-000000000001", "baseVersion": null, "updatedAt": "2026-10-19T20:00:00Z" }, "revision": "20000000-0000-4000-8000-000000000001" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/templates/{templateId}/draft": { "get": { "operationId": "getTemplatesTemplateIdDraft", "summary": "Consultar/salvar rascunho com revisão própria", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "templates" ], "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "templates:read", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateDraftEnvelope" }, "example": { "data": { "templateId": "60000000-0000-4000-8000-000000000001", "config": { "schemaVersion": 1, "kind": "preset", "baseTemplateId": "android", "rendererContractVersion": 1, "appearance": { "light": { "background": "#f8fafc", "surface": "#ffffff", "border": "#e2e8f0", "text": "#0f172a", "muted": "#64748b", "accent": "#0284c7", "secondary": "#059669", "tertiary": "#f1f5f9" }, "dark": { "background": "#0c0d0e", "surface": "#141517", "border": "#26272b", "text": "#f4f4f5", "muted": "#a1a1aa", "accent": "#0284c7", "secondary": "#10b981", "tertiary": "#1c1d20" }, "fontFamily": "system", "radius": "large", "spacing": "comfortable" }, "content": {}, "variables": [] }, "revision": "20000000-0000-4000-8000-000000000001", "baseVersion": null, "updatedAt": "2026-10-19T20:00:00Z" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "put": { "operationId": "setTemplatesTemplateIdDraft", "summary": "Consultar/salvar rascunho com revisão própria", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "templates" ], "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "templates:update", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateDraftPut" }, "example": { "config": { "schemaVersion": 1, "kind": "preset", "baseTemplateId": "android", "rendererContractVersion": 1, "appearance": { "light": { "background": "#f8fafc", "surface": "#ffffff", "border": "#e2e8f0", "text": "#0f172a", "muted": "#64748b", "accent": "#0284c7", "secondary": "#059669", "tertiary": "#f1f5f9" }, "dark": { "background": "#0c0d0e", "surface": "#141517", "border": "#26272b", "text": "#f4f4f5", "muted": "#a1a1aa", "accent": "#0284c7", "secondary": "#10b981", "tertiary": "#1c1d20" }, "fontFamily": "system", "radius": "large", "spacing": "comfortable" }, "content": {}, "variables": [] } } } } }, "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateDraftEnvelope" }, "example": { "data": { "templateId": "60000000-0000-4000-8000-000000000001", "config": { "schemaVersion": 1, "kind": "preset", "baseTemplateId": "android", "rendererContractVersion": 1, "appearance": { "light": { "background": "#f8fafc", "surface": "#ffffff", "border": "#e2e8f0", "text": "#0f172a", "muted": "#64748b", "accent": "#0284c7", "secondary": "#059669", "tertiary": "#f1f5f9" }, "dark": { "background": "#0c0d0e", "surface": "#141517", "border": "#26272b", "text": "#f4f4f5", "muted": "#a1a1aa", "accent": "#0284c7", "secondary": "#10b981", "tertiary": "#1c1d20" }, "fontFamily": "system", "radius": "large", "spacing": "comfortable" }, "content": {}, "variables": [] }, "revision": "20000000-0000-4000-8000-000000000001", "baseVersion": null, "updatedAt": "2026-10-19T20:00:00Z" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/templates/{templateId}/validate": { "post": { "operationId": "validateTemplatesTemplateId", "summary": "Validar configuração e variáveis", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "templates" ], "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "templates:validate", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateValidate" }, "example": { "config": { "schemaVersion": 1, "kind": "preset", "baseTemplateId": "android", "rendererContractVersion": 1, "appearance": { "light": { "background": "#f8fafc", "surface": "#ffffff", "border": "#e2e8f0", "text": "#0f172a", "muted": "#64748b", "accent": "#0284c7", "secondary": "#059669", "tertiary": "#f1f5f9" }, "dark": { "background": "#0c0d0e", "surface": "#141517", "border": "#26272b", "text": "#f4f4f5", "muted": "#a1a1aa", "accent": "#0284c7", "secondary": "#10b981", "tertiary": "#1c1d20" }, "fontFamily": "system", "radius": "large", "spacing": "comfortable" }, "content": {}, "variables": [] }, "usage": "link" } } } }, "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateValidationResultEnvelope" }, "example": { "data": { "valid": true, "config": { "schemaVersion": 1, "kind": "preset", "baseTemplateId": "android", "rendererContractVersion": 1, "appearance": { "light": { "background": "#f8fafc", "surface": "#ffffff", "border": "#e2e8f0", "text": "#0f172a", "muted": "#64748b", "accent": "#0284c7", "secondary": "#059669", "tertiary": "#f1f5f9" }, "dark": { "background": "#0c0d0e", "surface": "#141517", "border": "#26272b", "text": "#f4f4f5", "muted": "#a1a1aa", "accent": "#0284c7", "secondary": "#10b981", "tertiary": "#1c1d20" }, "fontFamily": "system", "radius": "large", "spacing": "comfortable" }, "content": {}, "variables": [] }, "usage": "link" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/templates/{templateId}/preview": { "post": { "operationId": "previewTemplatesTemplateId", "summary": "Prévia com dados autorizados, sem publicação", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "templates" ], "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "templates:preview", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplatePreview" }, "example": { "config": { "schemaVersion": 1, "kind": "preset", "baseTemplateId": "android", "rendererContractVersion": 1, "appearance": { "light": { "background": "#f8fafc", "surface": "#ffffff", "border": "#e2e8f0", "text": "#0f172a", "muted": "#64748b", "accent": "#0284c7", "secondary": "#059669", "tertiary": "#f1f5f9" }, "dark": { "background": "#0c0d0e", "surface": "#141517", "border": "#26272b", "text": "#f4f4f5", "muted": "#a1a1aa", "accent": "#0284c7", "secondary": "#10b981", "tertiary": "#1c1d20" }, "fontFamily": "system", "radius": "large", "spacing": "comfortable" }, "content": {}, "variables": [] } } } } }, "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplatePreviewResultEnvelope" }, "example": { "data": { "templateId": "60000000-0000-4000-8000-000000000001", "config": { "schemaVersion": 1, "kind": "preset", "baseTemplateId": "android", "rendererContractVersion": 1, "appearance": { "light": { "background": "#f8fafc", "surface": "#ffffff", "border": "#e2e8f0", "text": "#0f172a", "muted": "#64748b", "accent": "#0284c7", "secondary": "#059669", "tertiary": "#f1f5f9" }, "dark": { "background": "#0c0d0e", "surface": "#141517", "border": "#26272b", "text": "#f4f4f5", "muted": "#a1a1aa", "accent": "#0284c7", "secondary": "#10b981", "tertiary": "#1c1d20" }, "fontFamily": "system", "radius": "large", "spacing": "comfortable" }, "content": {}, "variables": [] }, "content": { "heading": "Loja" }, "sideEffects": false, "rendererContractVersion": 1 }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/templates/{templateId}/versions": { "get": { "operationId": "getTemplatesTemplateIdVersions", "summary": "Listar/preparar snapshots imutáveis", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "templates" ], "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Cursor" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "templates:read", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateVersionListEnvelope" }, "example": { "data": [ { "templateId": "60000000-0000-4000-8000-000000000001", "version": 1, "state": "prepared", "config": { "schemaVersion": 1, "kind": "preset", "baseTemplateId": "android", "rendererContractVersion": 1, "appearance": { "light": { "background": "#f8fafc", "surface": "#ffffff", "border": "#e2e8f0", "text": "#0f172a", "muted": "#64748b", "accent": "#0284c7", "secondary": "#059669", "tertiary": "#f1f5f9" }, "dark": { "background": "#0c0d0e", "surface": "#141517", "border": "#26272b", "text": "#f4f4f5", "muted": "#a1a1aa", "accent": "#0284c7", "secondary": "#10b981", "tertiary": "#1c1d20" }, "fontFamily": "system", "radius": "large", "spacing": "comfortable" }, "content": {}, "variables": [] }, "checksum": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "usage": "link", "authorId": "40000000-0000-4000-8000-000000000001", "createdAt": "2026-10-19T20:00:00Z" } ], "pagination": { "hasMore": false, "nextCursor": null }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "post": { "operationId": "createTemplatesTemplateIdVersions", "summary": "Listar/preparar snapshots imutáveis", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "templates" ], "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "templates:snapshot", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateVersionCreate" }, "example": { "draftRevision": "20000000-0000-4000-8000-000000000001", "usage": "link" } } } }, "responses": { "201": { "description": "Criado. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" }, "Location": { "description": "Endereço relativo do recurso criado.", "schema": { "type": "string" }, "example": "/v1/templates/60000000-0000-4000-8000-000000000001/versions/1" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateSnapshotEnvelope" }, "example": { "data": { "template": { "id": "60000000-0000-4000-8000-000000000001", "appId": "app_loja", "name": "Página da loja", "baseTemplateId": "android", "archived": false, "revision": "20000000-0000-4000-8000-000000000001", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z" }, "version": { "templateId": "60000000-0000-4000-8000-000000000001", "version": 1, "state": "prepared", "config": { "schemaVersion": 1, "kind": "preset", "baseTemplateId": "android", "rendererContractVersion": 1, "appearance": { "light": { "background": "#f8fafc", "surface": "#ffffff", "border": "#e2e8f0", "text": "#0f172a", "muted": "#64748b", "accent": "#0284c7", "secondary": "#059669", "tertiary": "#f1f5f9" }, "dark": { "background": "#0c0d0e", "surface": "#141517", "border": "#26272b", "text": "#f4f4f5", "muted": "#a1a1aa", "accent": "#0284c7", "secondary": "#10b981", "tertiary": "#1c1d20" }, "fontFamily": "system", "radius": "large", "spacing": "comfortable" }, "content": {}, "variables": [] }, "checksum": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "usage": "link", "authorId": "40000000-0000-4000-8000-000000000001", "createdAt": "2026-10-19T20:00:00Z" }, "draft": { "revision": "20000000-0000-4000-8000-000000000001", "baseVersion": 1, "updatedAt": "2026-10-19T20:00:00Z" }, "revision": "20000000-0000-4000-8000-000000000001" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/templates/{templateId}/versions/{version}": { "get": { "operationId": "getTemplatesTemplateIdVersionsVersion", "summary": "Consultar snapshot", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "templates" ], "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "version", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "templates:read", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateVersionEnvelope" }, "example": { "data": { "templateId": "60000000-0000-4000-8000-000000000001", "version": 1, "state": "prepared", "config": { "schemaVersion": 1, "kind": "preset", "baseTemplateId": "android", "rendererContractVersion": 1, "appearance": { "light": { "background": "#f8fafc", "surface": "#ffffff", "border": "#e2e8f0", "text": "#0f172a", "muted": "#64748b", "accent": "#0284c7", "secondary": "#059669", "tertiary": "#f1f5f9" }, "dark": { "background": "#0c0d0e", "surface": "#141517", "border": "#26272b", "text": "#f4f4f5", "muted": "#a1a1aa", "accent": "#0284c7", "secondary": "#10b981", "tertiary": "#1c1d20" }, "fontFamily": "system", "radius": "large", "spacing": "comfortable" }, "content": {}, "variables": [] }, "checksum": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "usage": "link", "authorId": "40000000-0000-4000-8000-000000000001", "createdAt": "2026-10-19T20:00:00Z" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/templates/{templateId}/availability": { "get": { "operationId": "getTemplatesTemplateIdAvailability", "summary": "Versões disponíveis para associação", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "templates" ], "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Cursor" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "templates:read", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateAvailabilityListEnvelope" }, "example": { "data": [ { "version": 1, "confirmedAt": "2026-10-19T20:00:00Z" } ], "pagination": { "hasMore": false, "nextCursor": null }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/templates/{templateId}/publish": { "post": { "operationId": "publishTemplatesTemplateId", "summary": "Publicar versão com alvos explícitos", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "templates" ], "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "templates:publish", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplatePublish" }, "example": { "version": 1, "targets": [] } } } }, "responses": { "202": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" }, "Location": { "description": "Publicação a acompanhar.", "schema": { "type": "string" }, "example": "/v1/template-publications/60000000-0000-4000-8000-000000000001" }, "Retry-After": { "description": "Segundos até a próxima consulta.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplatePublicationEnvelope" }, "example": { "data": { "id": "60000000-0000-4000-8000-000000000001", "appId": "app_loja", "revision": "20000000-0000-4000-8000-000000000001", "action": "publish", "baseTemplateId": "android", "choice": { "mode": "custom", "templateId": "60000000-0000-4000-8000-000000000001", "version": 1 }, "state": "queued", "phase": "version", "error": null, "versionAvailability": "prepared", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z", "targets": [] }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/templates/{templateId}/restore": { "post": { "operationId": "restoreTemplatesTemplateId", "summary": "Restaurar versão confirmada", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "templates" ], "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "templates:publish", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateRestore" }, "example": { "version": 1, "targets": [] } } } }, "responses": { "202": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" }, "Location": { "description": "Publicação a acompanhar.", "schema": { "type": "string" }, "example": "/v1/template-publications/60000000-0000-4000-8000-000000000001" }, "Retry-After": { "description": "Segundos até a próxima consulta.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplatePublicationEnvelope" }, "example": { "data": { "id": "60000000-0000-4000-8000-000000000001", "appId": "app_loja", "revision": "20000000-0000-4000-8000-000000000001", "action": "publish", "baseTemplateId": "android", "choice": { "mode": "custom", "templateId": "60000000-0000-4000-8000-000000000001", "version": 1 }, "state": "queued", "phase": "version", "error": null, "versionAvailability": "prepared", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z", "targets": [] }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/template-publications": { "get": { "operationId": "getTemplatePublications", "summary": "Listar publicações por app/template/alvo", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "template-publications" ], "parameters": [ { "name": "appId", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AppId" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Cursor" } }, { "name": "baseTemplateId", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/BaseId" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "templates:read", "x-agilink-resource-scope": "query_or_body_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplatePublicationListEnvelope" }, "example": { "data": [ { "id": "60000000-0000-4000-8000-000000000001", "appId": "app_loja", "revision": "20000000-0000-4000-8000-000000000001", "action": "publish", "baseTemplateId": "android", "choice": { "mode": "custom", "templateId": "60000000-0000-4000-8000-000000000001", "version": 1 }, "state": "queued", "phase": "version", "error": null, "versionAvailability": "prepared", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z", "targets": [] } ], "pagination": { "hasMore": false, "nextCursor": null }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/template-publications/{publicationId}": { "get": { "operationId": "getTemplatePublicationsPublicationId", "summary": "Estado detalhado por destino", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "template-publications" ], "parameters": [ { "name": "publicationId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "templates:read", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplatePublicationEnvelope" }, "example": { "data": { "id": "60000000-0000-4000-8000-000000000001", "appId": "app_loja", "revision": "20000000-0000-4000-8000-000000000001", "action": "publish", "baseTemplateId": "android", "choice": { "mode": "custom", "templateId": "60000000-0000-4000-8000-000000000001", "version": 1 }, "state": "queued", "phase": "version", "error": null, "versionAvailability": "prepared", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z", "targets": [] }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/template-publications/{publicationId}/retry": { "post": { "operationId": "retryTemplatePublicationsPublicationId", "summary": "Repetir tentativa recuperável", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "template-publications" ], "parameters": [ { "name": "publicationId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "templates:retry", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A3b", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyObject" }, "example": {} } } }, "responses": { "202": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" }, "Location": { "description": "Publicação a acompanhar.", "schema": { "type": "string" }, "example": "/v1/template-publications/60000000-0000-4000-8000-000000000001" }, "Retry-After": { "description": "Segundos até a próxima consulta.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplatePublicationEnvelope" }, "example": { "data": { "id": "60000000-0000-4000-8000-000000000001", "appId": "app_loja", "revision": "20000000-0000-4000-8000-000000000001", "action": "publish", "baseTemplateId": "android", "choice": { "mode": "custom", "templateId": "60000000-0000-4000-8000-000000000001", "version": 1 }, "state": "queued", "phase": "version", "error": null, "versionAvailability": "prepared", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z", "targets": [] }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/analytics/summary": { "get": { "operationId": "getAnalyticsSummary", "summary": "Totais e indicadores por período/filtros", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "analytics" ], "parameters": [ { "name": "appId", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AppId" } }, { "name": "start", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AnalyticsInstant" } }, { "name": "end", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AnalyticsInstant" } }, { "name": "timezone", "in": "query", "required": false, "schema": { "type": "string", "default": "America/Sao_Paulo", "maxLength": 100 } }, { "name": "group", "in": "query", "required": false, "schema": { "enum": [ "all", "main", "operational" ], "default": "all" } }, { "name": "linkId", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/LinkId" } }, { "name": "domain", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Domain" } }, { "name": "prefix", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "campaignId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "folderId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "tagId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "device", "in": "query", "required": false, "schema": { "enum": [ "android", "ios", "desktop", "unknown" ] } }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 7 } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "analytics:read", "x-agilink-resource-scope": "query_or_body_app", "x-agilink-milestone": "A3c", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsSummaryEnvelope" }, "example": { "data": { "appId": "app_loja", "period": { "start": "2026-10-01T00:00:00Z", "end": "2026-10-02T00:00:00Z", "timezone": "America/Sao_Paulo", "startInclusive": true, "endExclusive": true }, "filters": { "campaignId": null, "folderId": null, "tagId": null, "group": "all", "linkId": null, "domain": null, "prefix": null, "device": null, "source": null, "country": null, "eventType": "all" }, "generatedAt": "2026-10-02T12:00:00Z", "coverage": { "source": "event_rows", "grouping": "current_link_group", "deletedLinks": "excluded", "historicalAggregates": "not_merged", "uniqueVisitors": "distinct_click_hash_estimate", "nativeTrust": "client_reported", "completenessGuaranteed": false, "limitations": [ "Totais calculados das linhas disponíveis; agregados históricos não são somados.", "Abertura não comprova instalação." ] }, "totals": { "clicks": 3, "uniqueVisitors": 1, "identifiedClicks": 2, "appOpens": 2, "contentViews": 1, "legacyContentLoads": 0, "activeLinks": 1, "firstEventAt": "2026-10-01T01:00:00Z", "lastEventAt": "2026-10-01T02:00:00Z" } }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/analytics/timeseries": { "get": { "operationId": "getAnalyticsTimeseries", "summary": "Série com granularidade suportada", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "analytics" ], "parameters": [ { "name": "appId", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AppId" } }, { "name": "start", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AnalyticsInstant" } }, { "name": "end", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AnalyticsInstant" } }, { "name": "timezone", "in": "query", "required": false, "schema": { "type": "string", "default": "America/Sao_Paulo", "maxLength": 100 } }, { "name": "group", "in": "query", "required": false, "schema": { "enum": [ "all", "main", "operational" ], "default": "all" } }, { "name": "linkId", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/LinkId" } }, { "name": "domain", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Domain" } }, { "name": "prefix", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "campaignId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "folderId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "tagId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "device", "in": "query", "required": false, "schema": { "enum": [ "android", "ios", "desktop", "unknown" ] } }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 7 } }, { "name": "granularity", "in": "query", "required": false, "schema": { "enum": [ "hour", "day", "month", "year" ], "default": "day" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "analytics:read", "x-agilink-resource-scope": "query_or_body_app", "x-agilink-milestone": "A3c", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsTimeseriesEnvelope" }, "example": { "data": { "appId": "app_loja", "period": { "start": "2026-10-01T00:00:00Z", "end": "2026-10-02T00:00:00Z", "timezone": "America/Sao_Paulo", "startInclusive": true, "endExclusive": true }, "filters": { "campaignId": null, "folderId": null, "tagId": null, "group": "all", "linkId": null, "domain": null, "prefix": null, "device": null, "source": null, "country": null, "eventType": "all" }, "generatedAt": "2026-10-02T12:00:00Z", "coverage": { "source": "event_rows", "grouping": "current_link_group", "deletedLinks": "excluded", "historicalAggregates": "not_merged", "uniqueVisitors": "distinct_click_hash_estimate", "nativeTrust": "client_reported", "completenessGuaranteed": false, "limitations": [ "Totais calculados das linhas disponíveis; agregados históricos não são somados.", "Abertura não comprova instalação." ] }, "granularity": "day", "sparse": true, "buckets": [ { "start": "2026-09-30T03:00:00Z", "localLabel": "2026-09-30T00:00", "clicks": 3, "uniqueVisitors": 1, "identifiedClicks": 2, "appOpens": 2, "contentViews": 1, "legacyContentLoads": 0 } ] }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/analytics/breakdown": { "get": { "operationId": "getAnalyticsBreakdown", "summary": "Dimensões disponíveis e valores agregados", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "analytics" ], "parameters": [ { "name": "appId", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AppId" } }, { "name": "start", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AnalyticsInstant" } }, { "name": "end", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AnalyticsInstant" } }, { "name": "timezone", "in": "query", "required": false, "schema": { "type": "string", "default": "America/Sao_Paulo", "maxLength": 100 } }, { "name": "group", "in": "query", "required": false, "schema": { "enum": [ "all", "main", "operational" ], "default": "all" } }, { "name": "linkId", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/LinkId" } }, { "name": "domain", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Domain" } }, { "name": "prefix", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "campaignId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "folderId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "tagId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "device", "in": "query", "required": false, "schema": { "enum": [ "android", "ios", "desktop", "unknown" ] } }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 7 } }, { "name": "dimension", "in": "query", "required": true, "schema": { "enum": [ "device", "source", "country", "eventType", "producer", "entryMethod" ] } }, { "name": "eventType", "in": "query", "required": false, "schema": { "enum": [ "all", "click", "app_open", "content_view", "legacy_content_load" ], "default": "click" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "analytics:read", "x-agilink-resource-scope": "query_or_body_app", "x-agilink-milestone": "A3c", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsBreakdownEnvelope" }, "example": { "data": { "appId": "app_loja", "period": { "start": "2026-10-01T00:00:00Z", "end": "2026-10-02T00:00:00Z", "timezone": "America/Sao_Paulo", "startInclusive": true, "endExclusive": true }, "filters": { "campaignId": null, "folderId": null, "tagId": null, "group": "all", "linkId": null, "domain": null, "prefix": null, "device": null, "source": null, "country": null, "eventType": "all" }, "generatedAt": "2026-10-02T12:00:00Z", "coverage": { "source": "event_rows", "grouping": "current_link_group", "deletedLinks": "excluded", "historicalAggregates": "not_merged", "uniqueVisitors": "distinct_click_hash_estimate", "nativeTrust": "client_reported", "completenessGuaranteed": false, "limitations": [ "Totais calculados das linhas disponíveis; agregados históricos não são somados.", "Abertura não comprova instalação." ] }, "dimension": "device", "truncated": false, "items": [ { "value": "android", "events": 6, "clicks": 3, "uniqueVisitors": 1, "identifiedClicks": 2, "appOpens": 2, "contentViews": 1, "legacyContentLoads": 0 } ] }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/analytics/top-links": { "get": { "operationId": "getAnalyticsTopLinks", "summary": "Ranking paginado", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "analytics" ], "parameters": [ { "name": "appId", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AppId" } }, { "name": "start", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AnalyticsInstant" } }, { "name": "end", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AnalyticsInstant" } }, { "name": "timezone", "in": "query", "required": false, "schema": { "type": "string", "default": "America/Sao_Paulo", "maxLength": 100 } }, { "name": "group", "in": "query", "required": false, "schema": { "enum": [ "all", "main", "operational" ], "default": "all" } }, { "name": "linkId", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/LinkId" } }, { "name": "domain", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Domain" } }, { "name": "prefix", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "campaignId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "folderId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "tagId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "device", "in": "query", "required": false, "schema": { "enum": [ "android", "ios", "desktop", "unknown" ] } }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 7 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Cursor" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "analytics:read", "x-agilink-resource-scope": "query_or_body_app", "x-agilink-milestone": "A3c", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsTopLinksEnvelope" }, "example": { "data": { "appId": "app_loja", "period": { "start": "2026-10-01T00:00:00Z", "end": "2026-10-02T00:00:00Z", "timezone": "America/Sao_Paulo", "startInclusive": true, "endExclusive": true }, "filters": { "campaignId": null, "folderId": null, "tagId": null, "group": "all", "linkId": null, "domain": null, "prefix": null, "device": null, "source": null, "country": null, "eventType": "all" }, "generatedAt": "2026-10-02T12:00:00Z", "coverage": { "source": "event_rows", "grouping": "current_link_group", "deletedLinks": "excluded", "historicalAggregates": "not_merged", "uniqueVisitors": "distinct_click_hash_estimate", "nativeTrust": "client_reported", "completenessGuaranteed": false, "limitations": [ "Totais calculados das linhas disponíveis; agregados históricos não são somados.", "Abertura não comprova instalação." ] }, "items": [ { "linkId": "go.example.com~-ofertas~-tenis", "title": "Tênis", "domain": "go.example.com", "prefix": "ofertas", "slug": "tenis", "clicks": 3, "uniqueVisitors": 1, "lastClickAt": "2026-10-01T02:00:00Z" } ] }, "pagination": { "hasMore": false, "nextCursor": null }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/analytics/events": { "get": { "operationId": "getAnalyticsEvents", "summary": "Eventos individuais autorizados e paginados", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "analytics" ], "parameters": [ { "name": "appId", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AppId" } }, { "name": "start", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AnalyticsInstant" } }, { "name": "end", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AnalyticsInstant" } }, { "name": "timezone", "in": "query", "required": false, "schema": { "type": "string", "default": "America/Sao_Paulo", "maxLength": 100 } }, { "name": "group", "in": "query", "required": false, "schema": { "enum": [ "all", "main", "operational" ], "default": "all" } }, { "name": "linkId", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/LinkId" } }, { "name": "domain", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Domain" } }, { "name": "prefix", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "campaignId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "folderId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "tagId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "device", "in": "query", "required": false, "schema": { "enum": [ "android", "ios", "desktop", "unknown" ] } }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 7 } }, { "name": "eventType", "in": "query", "required": false, "schema": { "enum": [ "all", "click", "app_open", "content_view", "legacy_content_load" ], "default": "click" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Cursor" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "analytics:read", "x-agilink-resource-scope": "query_or_body_app", "x-agilink-milestone": "A3c", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsEventsEnvelope" }, "example": { "data": { "appId": "app_loja", "period": { "start": "2026-10-01T00:00:00Z", "end": "2026-10-02T00:00:00Z", "timezone": "America/Sao_Paulo", "startInclusive": true, "endExclusive": true }, "filters": { "campaignId": null, "folderId": null, "tagId": null, "group": "all", "linkId": null, "domain": null, "prefix": null, "device": null, "source": null, "country": null, "eventType": "all" }, "generatedAt": "2026-10-02T12:00:00Z", "coverage": { "source": "event_rows", "grouping": "current_link_group", "deletedLinks": "excluded", "historicalAggregates": "not_merged", "uniqueVisitors": "distinct_click_hash_estimate", "nativeTrust": "client_reported", "completenessGuaranteed": false, "limitations": [ "Totais calculados das linhas disponíveis; agregados históricos não são somados.", "Abertura não comprova instalação." ] }, "events": [ { "id": "80000000-0000-4000-8000-000000000001", "appId": "app_loja", "linkId": "go.example.com~-ofertas~-tenis", "type": "click", "producer": "worker", "trust": "worker_observed", "occurredAt": "2026-10-01T01:00:00Z", "receivedAt": "2026-10-01T01:00:00Z", "device": "android", "source": "direct", "country": "BR", "entryMethod": "unknown", "openId": null, "parentEventId": null } ] }, "pagination": { "hasMore": false, "nextCursor": null }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/analytics/native": { "get": { "operationId": "getAnalyticsNative", "summary": "Aberturas, conteúdo e métricas nativas", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "analytics" ], "parameters": [ { "name": "appId", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AppId" } }, { "name": "start", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AnalyticsInstant" } }, { "name": "end", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AnalyticsInstant" } }, { "name": "timezone", "in": "query", "required": false, "schema": { "type": "string", "default": "America/Sao_Paulo", "maxLength": 100 } }, { "name": "group", "in": "query", "required": false, "schema": { "enum": [ "all", "main", "operational" ], "default": "all" } }, { "name": "linkId", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/LinkId" } }, { "name": "domain", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Domain" } }, { "name": "prefix", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "campaignId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "folderId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "tagId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "device", "in": "query", "required": false, "schema": { "enum": [ "android", "ios", "desktop", "unknown" ] } }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 7 } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "analytics:read", "x-agilink-resource-scope": "query_or_body_app", "x-agilink-milestone": "A3c", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsNativeEnvelope" }, "example": { "data": { "appId": "app_loja", "period": { "start": "2026-10-01T00:00:00Z", "end": "2026-10-02T00:00:00Z", "timezone": "America/Sao_Paulo", "startInclusive": true, "endExclusive": true }, "filters": { "campaignId": null, "folderId": null, "tagId": null, "group": "all", "linkId": null, "domain": null, "prefix": null, "device": null, "source": null, "country": null, "eventType": "all" }, "generatedAt": "2026-10-02T12:00:00Z", "coverage": { "source": "event_rows", "grouping": "current_link_group", "deletedLinks": "excluded", "historicalAggregates": "not_merged", "uniqueVisitors": "distinct_click_hash_estimate", "nativeTrust": "client_reported", "completenessGuaranteed": false, "limitations": [ "Totais calculados das linhas disponíveis; agregados históricos não são somados.", "Abertura não comprova instalação." ] }, "appOpens": 2, "contentViews": 1, "legacyContentLoads": 0, "confirmedOpens24h": 1, "matureOpens24h": 2, "provisionalOpens24h": 0, "cohortWindowHours": 24, "contentViewRate24h": 0.5 }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/analytics/recovery": { "get": { "operationId": "getAnalyticsRecovery", "summary": "Etapas e cobertura das recuperações implementadas", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "analytics" ], "parameters": [ { "name": "appId", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AppId" } }, { "name": "start", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AnalyticsInstant" } }, { "name": "end", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AnalyticsInstant" } }, { "name": "timezone", "in": "query", "required": false, "schema": { "type": "string", "default": "America/Sao_Paulo", "maxLength": 100 } }, { "name": "group", "in": "query", "required": false, "schema": { "enum": [ "all", "main", "operational" ], "default": "all" } }, { "name": "linkId", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/LinkId" } }, { "name": "domain", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Domain" } }, { "name": "prefix", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "analytics:read", "x-agilink-resource-scope": "query_or_body_app", "x-agilink-milestone": "A3c", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRecoveryEnvelope" }, "example": { "data": { "appId": "app_loja", "period": { "start": "2026-10-01T00:00:00Z", "end": "2026-10-02T00:00:00Z", "timezone": "America/Sao_Paulo", "startInclusive": true, "endExclusive": true }, "filters": { "campaignId": null, "folderId": null, "tagId": null, "group": "all", "linkId": null, "domain": null, "prefix": null, "device": null, "source": null, "country": null, "eventType": "all" }, "generatedAt": "2026-10-02T12:00:00Z", "coverage": { "source": "retained_recovery_tokens", "grouping": "current_link_group", "deletedLinks": "excluded", "historicalAggregates": "not_merged", "uniqueVisitors": "distinct_click_hash_estimate", "nativeTrust": "client_reported", "completenessGuaranteed": false, "limitations": [ "Totais calculados das linhas disponíveis; agregados históricos não são somados.", "Abertura não comprova instalação." ] }, "issuedTokens": 1, "stages": [ { "stage": "recovered", "eventCount": 1, "tokens": 1 } ] }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/links/{linkId}/history": { "get": { "operationId": "getLinksLinkIdHistory", "summary": "Histórico administrativo sanitizado de alterações", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "links" ], "parameters": [ { "name": "linkId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/LinkId" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Cursor" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "link_history:read", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A4a", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkHistoryListEnvelope" }, "example": { "data": [ { "id": "90000000-0000-4000-8000-000000000002", "linkId": "go.example.com~-ofertas~-tenis", "appId": "app_loja", "action": "update", "fields": [ "management" ], "revision": "20000000-0000-4000-8000-000000000001", "createdAt": "2026-10-19T20:00:00Z" } ], "pagination": { "hasMore": false, "nextCursor": null }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/links/{linkId}/tags": { "get": { "operationId": "getLinksLinkIdTags", "summary": "Ler/substituir associação de tags do mesmo app", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "links" ], "parameters": [ { "name": "linkId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/LinkId" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "tags:read", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A4a", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkTagsEnvelope" }, "example": { "data": { "linkId": "go.example.com~-ofertas~-tenis", "appId": "app_loja", "revision": "20000000-0000-4000-8000-000000000001", "tagIds": [] }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "put": { "operationId": "setLinksLinkIdTags", "summary": "Ler/substituir associação de tags do mesmo app", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "links" ], "parameters": [ { "name": "linkId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/LinkId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "tags:update", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A4a", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkTagsPut" }, "example": { "tagIds": [ "90000000-0000-4000-8000-000000000001" ] } } } }, "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkTagsEnvelope" }, "example": { "data": { "linkId": "go.example.com~-ofertas~-tenis", "appId": "app_loja", "revision": "20000000-0000-4000-8000-000000000001", "tagIds": [] }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/links/{linkId}/routing-rules": { "get": { "operationId": "getLinksLinkIdRoutingRules", "summary": "Ler/alterar regras avançadas previstas no pacote de expansão", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "links" ], "parameters": [ { "name": "linkId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/LinkId" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "routing_rules:read", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A4a", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkRoutingRulesEnvelope" }, "example": { "data": { "linkId": "go.example.com~-ofertas~-tenis", "appId": "app_loja", "revision": "20000000-0000-4000-8000-000000000001", "rules": [ { "id": "br", "platform": "desktop", "country": "BR", "startsAt": null, "expiresAt": null, "destinationUrl": "https://shop.example.com/br", "utm": {} } ] }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "put": { "operationId": "setLinksLinkIdRoutingRules", "summary": "Ler/alterar regras avançadas previstas no pacote de expansão", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "links" ], "parameters": [ { "name": "linkId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/LinkId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "routing_rules:update", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A4a", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingRulesPut" }, "example": { "rules": [ { "id": "br", "platform": "desktop", "country": "BR", "startsAt": null, "expiresAt": null, "destinationUrl": "https://shop.example.com/br", "utm": {} } ] } } } }, "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkRoutingRulesEnvelope" }, "example": { "data": { "linkId": "go.example.com~-ofertas~-tenis", "appId": "app_loja", "revision": "20000000-0000-4000-8000-000000000001", "rules": [ { "id": "br", "platform": "desktop", "country": "BR", "startsAt": null, "expiresAt": null, "destinationUrl": "https://shop.example.com/br", "utm": {} } ] }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/tags": { "get": { "operationId": "getTags", "summary": "Listar/criar etiquetas por app", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "tags" ], "parameters": [ { "name": "appId", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AppId" } }, { "name": "q", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/SearchText" } }, { "name": "archived", "in": "query", "required": false, "schema": { "enum": [ "all", "true", "false" ], "default": "all" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Cursor" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "tags:read", "x-agilink-resource-scope": "query_or_body_app", "x-agilink-milestone": "A4a", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationListEnvelope" }, "example": { "data": [ { "id": "90000000-0000-4000-8000-000000000001", "appId": "app_loja", "kind": "tags", "name": "Verão", "description": "Campanha de verão", "archived": false, "utm": {}, "revision": "20000000-0000-4000-8000-000000000001", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z" } ], "pagination": { "hasMore": false, "nextCursor": null }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "post": { "operationId": "createTags", "summary": "Listar/criar etiquetas por app", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "tags" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "tags:create", "x-agilink-resource-scope": "query_or_body_app", "x-agilink-milestone": "A4a", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationCreate" }, "example": { "appId": "app_loja", "name": "Verão" } } } }, "responses": { "201": { "description": "Criado. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" }, "Location": { "description": "Recurso criado.", "schema": { "type": "string" }, "example": "/v1/tags/90000000-0000-4000-8000-000000000001" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationEnvelope" }, "example": { "data": { "id": "90000000-0000-4000-8000-000000000001", "appId": "app_loja", "kind": "tags", "name": "Verão", "description": "Campanha de verão", "archived": false, "utm": {}, "revision": "20000000-0000-4000-8000-000000000001", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/tags/{tagId}": { "get": { "operationId": "getTagsTagId", "summary": "Consultar/renomear/remover etiqueta", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "tags" ], "parameters": [ { "name": "tagId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Revision" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "tags:read", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A4a", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationEnvelope" }, "example": { "data": { "id": "90000000-0000-4000-8000-000000000001", "appId": "app_loja", "kind": "tags", "name": "Verão", "description": "Campanha de verão", "archived": false, "utm": {}, "revision": "20000000-0000-4000-8000-000000000001", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "patch": { "operationId": "updateTagsTagId", "summary": "Consultar/renomear/remover etiqueta", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "tags" ], "parameters": [ { "name": "tagId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Revision" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "tags:update", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A4a", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationPatch" }, "example": { "name": "Verão 2027" } } } }, "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationEnvelope" }, "example": { "data": { "id": "90000000-0000-4000-8000-000000000001", "appId": "app_loja", "kind": "tags", "name": "Verão", "description": "Campanha de verão", "archived": false, "utm": {}, "revision": "20000000-0000-4000-8000-000000000001", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "delete": { "operationId": "deleteTagsTagId", "summary": "Consultar/renomear/remover etiqueta", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "tags" ], "parameters": [ { "name": "tagId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Revision" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "tags:delete", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A4a", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "204": { "description": "Removido. Corpo vazio; publicação da remoção acompanha outbox.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/folders": { "get": { "operationId": "getFolders", "summary": "Listar/criar pastas", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "folders" ], "parameters": [ { "name": "appId", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AppId" } }, { "name": "q", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/SearchText" } }, { "name": "archived", "in": "query", "required": false, "schema": { "enum": [ "all", "true", "false" ], "default": "all" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Cursor" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "folders:read", "x-agilink-resource-scope": "query_or_body_app", "x-agilink-milestone": "A4a", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationListEnvelope" }, "example": { "data": [ { "id": "90000000-0000-4000-8000-000000000001", "appId": "app_loja", "kind": "folders", "name": "Verão", "description": "Campanha de verão", "archived": false, "utm": {}, "revision": "20000000-0000-4000-8000-000000000001", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z" } ], "pagination": { "hasMore": false, "nextCursor": null }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "post": { "operationId": "createFolders", "summary": "Listar/criar pastas", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "folders" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "folders:create", "x-agilink-resource-scope": "query_or_body_app", "x-agilink-milestone": "A4a", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationCreate" }, "example": { "appId": "app_loja", "name": "Verão" } } } }, "responses": { "201": { "description": "Criado. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" }, "Location": { "description": "Recurso criado.", "schema": { "type": "string" }, "example": "/v1/folders/90000000-0000-4000-8000-000000000001" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationEnvelope" }, "example": { "data": { "id": "90000000-0000-4000-8000-000000000001", "appId": "app_loja", "kind": "folders", "name": "Verão", "description": "Campanha de verão", "archived": false, "utm": {}, "revision": "20000000-0000-4000-8000-000000000001", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/folders/{folderId}": { "get": { "operationId": "getFoldersFolderId", "summary": "Gerir pasta e restrições de remoção", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "folders" ], "parameters": [ { "name": "folderId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Revision" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "folders:read", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A4a", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationEnvelope" }, "example": { "data": { "id": "90000000-0000-4000-8000-000000000001", "appId": "app_loja", "kind": "folders", "name": "Verão", "description": "Campanha de verão", "archived": false, "utm": {}, "revision": "20000000-0000-4000-8000-000000000001", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "patch": { "operationId": "updateFoldersFolderId", "summary": "Gerir pasta e restrições de remoção", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "folders" ], "parameters": [ { "name": "folderId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Revision" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "folders:update", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A4a", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationPatch" }, "example": { "name": "Verão 2027" } } } }, "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationEnvelope" }, "example": { "data": { "id": "90000000-0000-4000-8000-000000000001", "appId": "app_loja", "kind": "folders", "name": "Verão", "description": "Campanha de verão", "archived": false, "utm": {}, "revision": "20000000-0000-4000-8000-000000000001", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "delete": { "operationId": "deleteFoldersFolderId", "summary": "Gerir pasta e restrições de remoção", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "folders" ], "parameters": [ { "name": "folderId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Revision" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "folders:delete", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A4a", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "204": { "description": "Removido. Corpo vazio; publicação da remoção acompanha outbox.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/campaigns": { "get": { "operationId": "getCampaigns", "summary": "Listar/criar campanhas", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "campaigns" ], "parameters": [ { "name": "appId", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AppId" } }, { "name": "q", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/SearchText" } }, { "name": "archived", "in": "query", "required": false, "schema": { "enum": [ "all", "true", "false" ], "default": "all" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Cursor" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "campaigns:read", "x-agilink-resource-scope": "query_or_body_app", "x-agilink-milestone": "A4a", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationListEnvelope" }, "example": { "data": [ { "id": "90000000-0000-4000-8000-000000000001", "appId": "app_loja", "kind": "campaigns", "name": "Verão", "description": "Campanha de verão", "archived": false, "utm": { "utm_source": "newsletter", "utm_campaign": "verao" }, "revision": "20000000-0000-4000-8000-000000000001", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z" } ], "pagination": { "hasMore": false, "nextCursor": null }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "post": { "operationId": "createCampaigns", "summary": "Listar/criar campanhas", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "campaigns" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "campaigns:create", "x-agilink-resource-scope": "query_or_body_app", "x-agilink-milestone": "A4a", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationCreate" }, "example": { "appId": "app_loja", "name": "Verão", "utm": { "utm_source": "newsletter", "utm_campaign": "verao" } } } } }, "responses": { "201": { "description": "Criado. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" }, "Location": { "description": "Recurso criado.", "schema": { "type": "string" }, "example": "/v1/campaigns/90000000-0000-4000-8000-000000000001" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationEnvelope" }, "example": { "data": { "id": "90000000-0000-4000-8000-000000000001", "appId": "app_loja", "kind": "campaigns", "name": "Verão", "description": "Campanha de verão", "archived": false, "utm": { "utm_source": "newsletter", "utm_campaign": "verao" }, "revision": "20000000-0000-4000-8000-000000000001", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/campaigns/{campaignId}": { "get": { "operationId": "getCampaignsCampaignId", "summary": "Gerir metadados, UTMs padrão e arquivamento", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "campaigns" ], "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Revision" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "campaigns:read", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A4a", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationEnvelope" }, "example": { "data": { "id": "90000000-0000-4000-8000-000000000001", "appId": "app_loja", "kind": "campaigns", "name": "Verão", "description": "Campanha de verão", "archived": false, "utm": { "utm_source": "newsletter", "utm_campaign": "verao" }, "revision": "20000000-0000-4000-8000-000000000001", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "patch": { "operationId": "updateCampaignsCampaignId", "summary": "Gerir metadados, UTMs padrão e arquivamento", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "campaigns" ], "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Revision" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "campaigns:update", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A4a", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationPatch" }, "example": { "name": "Verão 2027" } } } }, "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationEnvelope" }, "example": { "data": { "id": "90000000-0000-4000-8000-000000000001", "appId": "app_loja", "kind": "campaigns", "name": "Verão", "description": "Campanha de verão", "archived": false, "utm": { "utm_source": "newsletter", "utm_campaign": "verao" }, "revision": "20000000-0000-4000-8000-000000000001", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "delete": { "operationId": "deleteCampaignsCampaignId", "summary": "Gerir metadados, UTMs padrão e arquivamento", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "campaigns" ], "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Revision" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "campaigns:delete", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A4a", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "204": { "description": "Removido. Corpo vazio; publicação da remoção acompanha outbox.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/campaigns/{campaignId}/links": { "get": { "operationId": "getCampaignsCampaignIdLinks", "summary": "Links vinculados, paginados", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "campaigns" ], "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Revision" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Cursor" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "campaigns:read", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A4a", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkListEnvelope" }, "example": { "data": [ { "id": "go.example.com~-ofertas~-tenis", "appId": "app_loja", "domain": "go.example.com", "prefix": "ofertas", "slug": "tenis", "url": "https://go.example.com/ofertas/tenis", "title": "Tênis da campanha", "description": null, "imageUrl": null, "desktopUrl": "https://shop.example.com/produtos/tenis", "appPath": "produtos/tenis", "parameters": {}, "webOnly": false, "behavior": "manual", "group": "operational", "origin": "api", "revision": "20000000-0000-4000-8000-000000000001", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z", "publication": { "status": "pending", "desiredRevision": "20000000-0000-4000-8000-000000000001", "confirmedRevision": null, "updatedAt": "2026-10-19T20:00:00Z" } } ], "pagination": { "nextCursor": null, "hasMore": false }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/analytics/campaigns/{campaignId}": { "get": { "operationId": "getAnalyticsCampaignsCampaignId", "summary": "Métricas vinculadas à campanha", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "analytics" ], "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Revision" } }, { "name": "start", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AnalyticsInstant" } }, { "name": "end", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AnalyticsInstant" } }, { "name": "timezone", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 } }, { "name": "group", "in": "query", "required": false, "schema": { "enum": [ "all", "main", "operational" ], "default": "all" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "analytics:read", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A4a", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsSummaryEnvelope" }, "example": { "data": { "appId": "app_loja", "period": { "start": "2026-10-01T00:00:00Z", "end": "2026-10-02T00:00:00Z", "timezone": "America/Sao_Paulo", "startInclusive": true, "endExclusive": true }, "filters": { "campaignId": "90000000-0000-4000-8000-000000000001", "folderId": null, "tagId": null, "group": "all", "linkId": null, "domain": null, "prefix": null, "device": null, "source": null, "country": null, "eventType": "all" }, "generatedAt": "2026-10-02T12:00:00Z", "coverage": { "source": "event_rows", "grouping": "current_link_group", "deletedLinks": "excluded", "historicalAggregates": "not_merged", "uniqueVisitors": "distinct_click_hash_estimate", "nativeTrust": "client_reported", "completenessGuaranteed": false, "limitations": [ "Totais calculados das linhas disponíveis; agregados históricos não são somados.", "Abertura não comprova instalação." ] }, "totals": { "clicks": 3, "uniqueVisitors": 1, "identifiedClicks": 2, "appOpens": 2, "contentViews": 1, "legacyContentLoads": 0, "activeLinks": 1, "firstEventAt": "2026-10-01T01:00:00Z", "lastEventAt": "2026-10-01T02:00:00Z" } }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/links/{linkId}/qr": { "get": { "operationId": "getLinksLinkIdQr", "summary": "Gerar QR do endereço público do link em PNG/SVG com opções limitadas", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "links" ], "parameters": [ { "name": "linkId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/LinkId" } }, { "name": "format", "in": "query", "required": false, "schema": { "enum": [ "png", "svg" ], "default": "png" } }, { "name": "size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 256, "maximum": 1024, "default": 512 } }, { "name": "margin", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 4, "maximum": 16, "default": 4 } }, { "name": "errorCorrectionLevel", "in": "query", "required": false, "schema": { "enum": [ "M", "Q", "H" ], "default": "M" } }, { "name": "dark", "in": "query", "required": false, "schema": { "enum": [ "#000000", "#0f172a" ], "default": "#0f172a" } }, { "name": "light", "in": "query", "required": false, "schema": { "const": "#ffffff" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "qr_codes:read", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A4a", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "QR do endereço público; não é uma contagem de scans.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/svg+xml": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/qr-codes": { "get": { "operationId": "getQrCodes", "summary": "Listar/criar configurações persistidas de QR", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "qr-codes" ], "parameters": [ { "name": "appId", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AppId" } }, { "name": "q", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/SearchText" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Cursor" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "qr_codes:read", "x-agilink-resource-scope": "query_or_body_app", "x-agilink-milestone": "A4a", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QrCodeListEnvelope" }, "example": { "data": [ { "id": "90000000-0000-4000-8000-000000000002", "appId": "app_loja", "linkId": "go.example.com~-ofertas~-tenis", "url": "https://go.example.com/ofertas/tenis", "name": "Vitrine", "style": { "size": 512, "margin": 4, "errorCorrectionLevel": "M", "dark": "#0f172a", "light": "#ffffff" }, "revision": "20000000-0000-4000-8000-000000000001", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z" } ], "pagination": { "hasMore": false, "nextCursor": null }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "post": { "operationId": "createQrCodes", "summary": "Listar/criar configurações persistidas de QR", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "qr-codes" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "qr_codes:create", "x-agilink-resource-scope": "query_or_body_app", "x-agilink-milestone": "A4a", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QrCreate" }, "example": { "appId": "app_loja", "linkId": "go.example.com~-ofertas~-tenis", "name": "Vitrine", "style": { "size": 512, "margin": 4, "errorCorrectionLevel": "M", "dark": "#0f172a", "light": "#ffffff" } } } } }, "responses": { "201": { "description": "Criado. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" }, "Location": { "description": "Recurso criado.", "schema": { "type": "string" }, "example": "/v1/qr-codes/90000000-0000-4000-8000-000000000002" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QrCodeEnvelope" }, "example": { "data": { "id": "90000000-0000-4000-8000-000000000002", "appId": "app_loja", "linkId": "go.example.com~-ofertas~-tenis", "url": "https://go.example.com/ofertas/tenis", "name": "Vitrine", "style": { "size": 512, "margin": 4, "errorCorrectionLevel": "M", "dark": "#0f172a", "light": "#ffffff" }, "revision": "20000000-0000-4000-8000-000000000001", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/qr-codes/{qrId}": { "get": { "operationId": "getQrCodesQrId", "summary": "Consultar QR e estilo salvo", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "qr-codes" ], "parameters": [ { "name": "qrId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Revision" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "qr_codes:read", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A4a", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QrCodeEnvelope" }, "example": { "data": { "id": "90000000-0000-4000-8000-000000000002", "appId": "app_loja", "linkId": "go.example.com~-ofertas~-tenis", "url": "https://go.example.com/ofertas/tenis", "name": "Vitrine", "style": { "size": 512, "margin": 4, "errorCorrectionLevel": "M", "dark": "#0f172a", "light": "#ffffff" }, "revision": "20000000-0000-4000-8000-000000000001", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "patch": { "operationId": "updateQrCodesQrId", "summary": "Atualizar nome e estilo do QR; vínculo imutável", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "qr-codes" ], "parameters": [ { "name": "qrId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Revision" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "qr_codes:update", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A4a", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QrPatch" }, "example": { "name": "Vitrine principal" } } } }, "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QrCodeEnvelope" }, "example": { "data": { "id": "90000000-0000-4000-8000-000000000002", "appId": "app_loja", "linkId": "go.example.com~-ofertas~-tenis", "url": "https://go.example.com/ofertas/tenis", "name": "Vitrine", "style": { "size": 512, "margin": 4, "errorCorrectionLevel": "M", "dark": "#0f172a", "light": "#ffffff" }, "revision": "20000000-0000-4000-8000-000000000001", "createdAt": "2026-10-19T20:00:00Z", "updatedAt": "2026-10-19T20:00:00Z" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "delete": { "operationId": "deleteQrCodesQrId", "summary": "Excluir configuração do QR; imagens distribuídas continuam válidas", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "qr-codes" ], "parameters": [ { "name": "qrId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Revision" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "qr_codes:delete", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A4a", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "204": { "description": "Removido. Corpo vazio; publicação da remoção acompanha outbox.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/qr-codes/{qrId}/download": { "get": { "operationId": "getQrCodesQrIdDownload", "summary": "Baixar arquivo no formato/tamanho permitido", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "qr-codes" ], "parameters": [ { "name": "qrId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Revision" } }, { "name": "format", "in": "query", "required": false, "schema": { "enum": [ "png", "svg" ], "default": "png" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "qr_codes:read", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A4a", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "QR do endereço público; não é uma contagem de scans.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/svg+xml": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/exports": { "post": { "operationId": "createExports", "summary": "Solicitar exportação de links, eventos ou relatórios", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "exports" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "exports:create", "x-agilink-resource-scope": "query_or_body_app", "x-agilink-milestone": "A4b", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportCreate" }, "example": { "appId": "app_loja", "dataset": "links", "format": "json" } } } }, "responses": { "202": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" }, "Location": { "description": "Recurso a acompanhar.", "schema": { "type": "string" }, "example": "/v1/operations/b0000000-0000-4000-8000-000000000001" }, "Retry-After": { "description": "Segundos até a próxima consulta.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationEnvelope" }, "example": { "data": { "id": "b0000000-0000-4000-8000-000000000001", "appId": "app_loja", "kind": "export", "state": "queued", "operationId": "b0000000-0000-4000-8000-000000000001", "revision": "20000000-0000-4000-8000-000000000001", "total": 1, "succeeded": 0, "failed": 0, "expiresAt": "2026-10-27T01:00:00Z", "createdAt": "2026-10-20T01:00:00Z", "updatedAt": "2026-10-20T01:00:00Z", "downloadUrl": null }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/exports/{exportId}": { "get": { "operationId": "getExportsExportId", "summary": "Consultar progresso, expiração e metadados", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "exports" ], "parameters": [ { "name": "exportId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "exports:read", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A4b", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationEnvelope" }, "example": { "data": { "id": "b0000000-0000-4000-8000-000000000001", "appId": "app_loja", "kind": "batch", "state": "queued", "operationId": "b0000000-0000-4000-8000-000000000001", "revision": "20000000-0000-4000-8000-000000000001", "total": 1, "succeeded": 0, "failed": 0, "expiresAt": "2026-10-27T01:00:00Z", "createdAt": "2026-10-20T01:00:00Z", "updatedAt": "2026-10-20T01:00:00Z", "downloadUrl": null }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/exports/{exportId}/download": { "get": { "operationId": "getExportsExportIdDownload", "summary": "Download autorizado ou URL temporária conforme política", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "exports" ], "parameters": [ { "name": "exportId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "exports:read", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A4b", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Download autenticado, expira em 24 horas, máximo 1000 registros / 1 MiB; CSV neutraliza fórmulas.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "type": "string", "format": "binary" } }, "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/link-batches": { "post": { "operationId": "createLinkBatches", "summary": "Criação/edição/movimentação/arquivamento/remoção em lote", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "link-batches" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "batches:create", "x-agilink-resource-scope": "query_or_body_app", "x-agilink-milestone": "A4b", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchCreate" }, "example": { "appId": "app_loja", "items": [ { "clientId": "row-1", "action": "create", "input": { "appId": "app_loja", "domain": "go.example.com", "slug": "importado", "desktopUrl": "https://shop.example.com/one" } } ] } } } }, "responses": { "202": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" }, "Location": { "description": "Recurso a acompanhar.", "schema": { "type": "string" }, "example": "/v1/operations/b0000000-0000-4000-8000-000000000001" }, "Retry-After": { "description": "Segundos até a próxima consulta.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationEnvelope" }, "example": { "data": { "id": "b0000000-0000-4000-8000-000000000001", "appId": "app_loja", "kind": "batch", "state": "queued", "operationId": "b0000000-0000-4000-8000-000000000001", "revision": "20000000-0000-4000-8000-000000000001", "total": 1, "succeeded": 0, "failed": 0, "expiresAt": "2026-10-27T01:00:00Z", "createdAt": "2026-10-20T01:00:00Z", "updatedAt": "2026-10-20T01:00:00Z", "downloadUrl": null }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/link-batches/{batchId}/items": { "get": { "operationId": "getLinkBatchesBatchIdItems", "summary": "Resultados por item, paginados", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "link-batches" ], "parameters": [ { "name": "batchId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Cursor" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "batches:read", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A4b", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationItemListEnvelope" }, "example": { "data": [ { "clientId": "row-1", "ordinal": 1, "state": "pending", "result": null, "error": null } ], "pagination": { "hasMore": false, "nextCursor": null }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/imports": { "post": { "operationId": "createImports", "summary": "Upload/registro de importação CSV/JSON", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "imports" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "imports:create", "x-agilink-resource-scope": "query_or_body_app", "x-agilink-milestone": "A4b", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportCreate" }, "example": { "appId": "app_loja", "format": "csv", "content": "domain,slug,desktopUrl\ngo.example.com,importado,https://shop.example.com/one" } } } }, "responses": { "201": { "description": "Criado. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" }, "Location": { "description": "Recurso criado.", "schema": { "type": "string" }, "example": "/v1/imports/b0000000-0000-4000-8000-000000000001" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationEnvelope" }, "example": { "data": { "id": "b0000000-0000-4000-8000-000000000001", "appId": "app_loja", "kind": "import", "state": "uploaded", "operationId": null, "revision": "20000000-0000-4000-8000-000000000001", "total": 1, "succeeded": 0, "failed": 0, "expiresAt": "2026-10-27T01:00:00Z", "createdAt": "2026-10-20T01:00:00Z", "updatedAt": "2026-10-20T01:00:00Z", "downloadUrl": null }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/imports/{importId}/validate": { "post": { "operationId": "validateImportsImportId", "summary": "Validar e produzir relatório sem gravar links", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "imports" ], "parameters": [ { "name": "importId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "imports:validate", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A4b", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyObject" }, "example": {} } } }, "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationEnvelope" }, "example": { "data": { "id": "b0000000-0000-4000-8000-000000000001", "appId": "app_loja", "kind": "import", "state": "validated", "operationId": null, "revision": "20000000-0000-4000-8000-000000000001", "total": 1, "succeeded": 0, "failed": 0, "expiresAt": "2026-10-27T01:00:00Z", "createdAt": "2026-10-20T01:00:00Z", "updatedAt": "2026-10-20T01:00:00Z", "downloadUrl": null }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/imports/{importId}/commit": { "post": { "operationId": "commitImportsImportId", "summary": "Executar importação validada", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "imports" ], "parameters": [ { "name": "importId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "imports:commit", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A4b", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyObject" }, "example": {} } } }, "responses": { "202": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" }, "Location": { "description": "Recurso a acompanhar.", "schema": { "type": "string" }, "example": "/v1/operations/b0000000-0000-4000-8000-000000000001" }, "Retry-After": { "description": "Segundos até a próxima consulta.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationEnvelope" }, "example": { "data": { "id": "b0000000-0000-4000-8000-000000000001", "appId": "app_loja", "kind": "import", "state": "queued", "operationId": "b0000000-0000-4000-8000-000000000001", "revision": "20000000-0000-4000-8000-000000000001", "total": 1, "succeeded": 0, "failed": 0, "expiresAt": "2026-10-27T01:00:00Z", "createdAt": "2026-10-20T01:00:00Z", "updatedAt": "2026-10-20T01:00:00Z", "downloadUrl": null }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/imports/{importId}": { "get": { "operationId": "getImportsImportId", "summary": "Resumo, estado e erros", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "imports" ], "parameters": [ { "name": "importId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "imports:read", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A4b", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationEnvelope" }, "example": { "data": { "id": "b0000000-0000-4000-8000-000000000001", "appId": "app_loja", "kind": "import", "state": "queued", "operationId": "b0000000-0000-4000-8000-000000000001", "revision": "20000000-0000-4000-8000-000000000001", "total": 1, "succeeded": 0, "failed": 0, "expiresAt": "2026-10-27T01:00:00Z", "createdAt": "2026-10-20T01:00:00Z", "updatedAt": "2026-10-20T01:00:00Z", "downloadUrl": null }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/imports/{importId}/items": { "get": { "operationId": "getImportsImportIdItems", "summary": "Resultados por linha", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "imports" ], "parameters": [ { "name": "importId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Cursor" } }, { "name": "format", "in": "query", "required": false, "schema": { "enum": [ "json", "csv" ] } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "imports:read", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A4b", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationItemListEnvelope" }, "example": { "data": [ { "clientId": "row-1", "ordinal": 1, "state": "pending", "result": null, "error": null } ], "pagination": { "hasMore": false, "nextCursor": null }, "meta": { "requestId": "req_00000000000040008000000000000001" } } }, "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/webhooks": { "get": { "operationId": "getWebhooks", "summary": "Listar/cadastrar destino e assinaturas de eventos", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "webhooks" ], "parameters": [ { "name": "appId", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/AppId" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Cursor" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "webhooks:read", "x-agilink-resource-scope": "query_or_body_app", "x-agilink-milestone": "A4b", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookListEnvelope" }, "example": { "data": [ { "id": "b0000000-0000-4000-8000-000000000001", "appId": "app_loja", "name": "Integração", "url": "https://hooks.example.com/agilink", "events": [ "link.created" ], "enabled": true, "failures": 0, "revision": "20000000-0000-4000-8000-000000000001", "previousSecretExpiresAt": null, "createdAt": "2026-10-20T01:00:00Z", "updatedAt": "2026-10-20T01:00:00Z" } ], "pagination": { "hasMore": false, "nextCursor": null }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "post": { "operationId": "createWebhooks", "summary": "Listar/cadastrar destino e assinaturas de eventos", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "webhooks" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "webhooks:create", "x-agilink-resource-scope": "query_or_body_app", "x-agilink-milestone": "A4b", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreate" }, "example": { "appId": "app_loja", "name": "Integração", "url": "https://hooks.example.com/agilink", "events": [ "link.created" ] } } } }, "responses": { "201": { "description": "Criado. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" }, "Location": { "description": "Recurso criado.", "schema": { "type": "string" }, "example": "/v1/webhooks/b0000000-0000-4000-8000-000000000001" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookIssuedEnvelope" }, "example": { "data": { "webhook": { "id": "b0000000-0000-4000-8000-000000000001", "appId": "app_loja", "name": "Integração", "url": "https://hooks.example.com/agilink", "events": [ "link.created" ], "enabled": true, "failures": 0, "revision": "20000000-0000-4000-8000-000000000001", "previousSecretExpiresAt": null, "createdAt": "2026-10-20T01:00:00Z", "updatedAt": "2026-10-20T01:00:00Z" }, "secret": "whsec_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/webhooks/{webhookId}": { "get": { "operationId": "getWebhooksWebhookId", "summary": "Consultar/alterar/desativar destino", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "webhooks" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "webhooks:read", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A4b", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" }, "example": { "data": { "id": "b0000000-0000-4000-8000-000000000001", "appId": "app_loja", "name": "Integração", "url": "https://hooks.example.com/agilink", "events": [ "link.created" ], "enabled": true, "failures": 0, "revision": "20000000-0000-4000-8000-000000000001", "previousSecretExpiresAt": null, "createdAt": "2026-10-20T01:00:00Z", "updatedAt": "2026-10-20T01:00:00Z" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "patch": { "operationId": "updateWebhooksWebhookId", "summary": "Consultar/alterar/desativar destino", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "webhooks" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "webhooks:update", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A4b", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPatch" }, "example": { "enabled": false } } } }, "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" }, "example": { "data": { "id": "b0000000-0000-4000-8000-000000000001", "appId": "app_loja", "name": "Integração", "url": "https://hooks.example.com/agilink", "events": [ "link.created" ], "enabled": true, "failures": 0, "revision": "20000000-0000-4000-8000-000000000001", "previousSecretExpiresAt": null, "createdAt": "2026-10-20T01:00:00Z", "updatedAt": "2026-10-20T01:00:00Z" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } }, "delete": { "operationId": "deleteWebhooksWebhookId", "summary": "Consultar/alterar/desativar destino", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "webhooks" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "webhooks:delete", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A4b", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "204": { "description": "Removido. Corpo vazio; publicação da remoção acompanha outbox.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/webhooks/{webhookId}/rotate-secret": { "post": { "operationId": "rotateSecretWebhooksWebhookId", "summary": "Rotacionar assinatura com período de transição", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "webhooks" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "webhooks:rotate_secret", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A4b", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRotate" }, "example": { "overlapSeconds": 3600 } } } }, "responses": { "201": { "description": "Criado. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" }, "Location": { "description": "Recurso criado.", "schema": { "type": "string" }, "example": "/v1/webhooks/b0000000-0000-4000-8000-000000000001" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookIssuedEnvelope" }, "example": { "data": { "webhook": { "id": "b0000000-0000-4000-8000-000000000001", "appId": "app_loja", "name": "Integração", "url": "https://hooks.example.com/agilink", "events": [ "link.created" ], "enabled": true, "failures": 0, "revision": "20000000-0000-4000-8000-000000000001", "previousSecretExpiresAt": null, "createdAt": "2026-10-20T01:00:00Z", "updatedAt": "2026-10-20T01:00:00Z" }, "secret": "whsec_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/webhooks/{webhookId}/test": { "post": { "operationId": "testWebhooksWebhookId", "summary": "Enviar evento sintético identificado como teste", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "webhooks" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "webhooks:test", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A4b", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyObject" }, "example": {} } } }, "responses": { "202": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" }, "Location": { "description": "Recurso a acompanhar.", "schema": { "type": "string" }, "example": "/v1/webhook-deliveries/b0000000-0000-4000-8000-000000000001" }, "Retry-After": { "description": "Segundos até a próxima consulta.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryEnvelope" }, "example": { "data": { "id": "b0000000-0000-4000-8000-000000000001", "appId": "app_loja", "webhookId": "b0000000-0000-4000-8000-000000000001", "eventId": "b0000000-0000-4000-8000-000000000001", "eventType": "webhook.test", "test": true, "state": "pending", "attempts": 0, "statusCode": null, "errorCode": null, "nextAttemptAt": "2026-10-20T01:00:00Z", "revision": "20000000-0000-4000-8000-000000000001", "createdAt": "2026-10-20T01:00:00Z", "expiresAt": "2026-10-27T01:00:00Z" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/webhooks/{webhookId}/deliveries": { "get": { "operationId": "getWebhooksWebhookIdDeliveries", "summary": "Histórico paginado", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "webhooks" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Cursor" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "webhooks:read", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A4b", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryListEnvelope" }, "example": { "data": [ { "id": "b0000000-0000-4000-8000-000000000001", "appId": "app_loja", "webhookId": "b0000000-0000-4000-8000-000000000001", "eventId": "b0000000-0000-4000-8000-000000000001", "eventType": "webhook.test", "test": true, "state": "pending", "attempts": 0, "statusCode": null, "errorCode": null, "nextAttemptAt": "2026-10-20T01:00:00Z", "revision": "20000000-0000-4000-8000-000000000001", "createdAt": "2026-10-20T01:00:00Z", "expiresAt": "2026-10-27T01:00:00Z" } ], "pagination": { "hasMore": false, "nextCursor": null }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/webhook-deliveries/{deliveryId}": { "get": { "operationId": "getWebhookDeliveriesDeliveryId", "summary": "Detalhe sanitizado", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "webhook-deliveries" ], "parameters": [ { "name": "deliveryId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "webhooks:read", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A4b", "x-agilink-future-oauth": "B1b_after_validation", "responses": { "200": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryEnvelope" }, "example": { "data": { "id": "b0000000-0000-4000-8000-000000000001", "appId": "app_loja", "webhookId": "b0000000-0000-4000-8000-000000000001", "eventId": "b0000000-0000-4000-8000-000000000001", "eventType": "webhook.test", "test": true, "state": "pending", "attempts": 0, "statusCode": null, "errorCode": null, "nextAttemptAt": "2026-10-20T01:00:00Z", "revision": "20000000-0000-4000-8000-000000000001", "createdAt": "2026-10-20T01:00:00Z", "expiresAt": "2026-10-27T01:00:00Z" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } }, "/webhook-deliveries/{deliveryId}/retry": { "post": { "operationId": "retryWebhookDeliveriesDeliveryId", "summary": "Reentrega explicitamente autorizada", "description": "Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.", "tags": [ "webhook-deliveries" ], "parameters": [ { "name": "deliveryId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OpaqueId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "description": "UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/IfMatch" }, "description": "ETag forte obtido em consulta. Ausência 428; revisão antiga 412." } ], "security": [ { "HumanSession": [] }, { "ApiKey": [] } ], "x-agilink-state": "available_production", "x-agilink-permission": "webhooks:retry", "x-agilink-resource-scope": "resource_owner_app", "x-agilink-milestone": "A4b", "x-agilink-future-oauth": "B1b_after_validation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyObject" }, "example": {} } } }, "responses": { "202": { "description": "Sucesso. Exemplo fictício.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "ETag": { "description": "Revisão forte, a enviar em If-Match na alteração.", "schema": { "$ref": "#/components/schemas/IfMatch" }, "example": "\"20000000-0000-4000-8000-000000000001\"" }, "Location": { "description": "Recurso a acompanhar.", "schema": { "type": "string" }, "example": "/v1/webhook-deliveries/b0000000-0000-4000-8000-000000000001" }, "Retry-After": { "description": "Segundos até a próxima consulta.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryEnvelope" }, "example": { "data": { "id": "b0000000-0000-4000-8000-000000000001", "appId": "app_loja", "webhookId": "b0000000-0000-4000-8000-000000000001", "eventId": "b0000000-0000-4000-8000-000000000001", "eventType": "webhook.test", "test": true, "state": "pending", "attempts": 0, "statusCode": null, "errorCode": null, "nextAttemptAt": "2026-10-20T01:00:00Z", "revision": "20000000-0000-4000-8000-000000000001", "createdAt": "2026-10-20T01:00:00Z", "expiresAt": "2026-10-27T01:00:00Z" }, "meta": { "requestId": "req_00000000000040008000000000000001" } } } } }, "400": { "description": "Cabeçalho, query, cursor ou JSON inválido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "invalid_request", "message": "Cabeçalho, query, cursor ou JSON inválido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#invalid-request" } } } } }, "401": { "description": "Credencial inválida, expirada ou revogada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "WWW-Authenticate": { "description": "Desafio de autenticação.", "schema": { "type": "string", "const": "Bearer" }, "example": "Bearer" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unauthenticated", "message": "Credencial inválida, expirada ou revogada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated" } } } } }, "403": { "description": "Operação sem permissão ou capacidade desabilitada.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "insufficient_permission", "message": "Operação sem permissão ou capacidade desabilitada.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission" } } } } }, "404": { "description": "Recurso inexistente ou fora dos aplicativos autorizados.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "not_found", "message": "Recurso inexistente ou fora dos aplicativos autorizados.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#not-found" } } } } }, "409": { "description": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "idempotency_conflict", "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict" } } } } }, "412": { "description": "Revisão não corresponde à atual.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "revision_conflict", "message": "Revisão não corresponde à atual.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict" } } } } }, "413": { "description": "Corpo excede o limite.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "payload_too_large", "message": "Corpo excede o limite.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#payload-too-large" } } } } }, "415": { "description": "Content-Type incompatível.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type incompatível.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#unsupported-media-type" } } } } }, "422": { "description": "JSON bem formado com dados de domínio inválidos.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "validation_failed", "message": "JSON bem formado com dados de domínio inválidos.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#validation-failed" } } } } }, "428": { "description": "If-Match obrigatório ausente.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "precondition_required", "message": "If-Match obrigatório ausente.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#precondition-required" } } } } }, "429": { "description": "Quota excedida. Respeitar Retry-After.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" }, "Retry-After": { "description": "Segundos até nova tentativa.", "schema": { "type": "integer", "minimum": 1 }, "example": 5 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "rate_limited", "message": "Quota excedida. Respeitar Retry-After.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited" } } } } }, "500": { "description": "Falha interna. Use requestId para diagnóstico.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "internal_error", "message": "Falha interna. Use requestId para diagnóstico.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#internal-error" } } } } }, "503": { "description": "Dependência indisponível; resultado da mutação pode ser incerto.", "headers": { "X-Request-Id": { "description": "Identificador gerado pelo servidor, inclusive para falhas e replays.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "Cache-Control": { "description": "Respostas administrativas não podem ser armazenadas.", "schema": { "type": "string", "const": "no-store, no-transform" }, "example": "no-store, no-transform" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "dependency_unavailable", "message": "Dependência indisponível; resultado da mutação pode ser incerto.", "requestId": "req_00000000000040008000000000000001", "documentationUrl": "https://docs.agilink.io/api/errors/#dependency-unavailable" } } } } } } } } }, "components": { "securitySchemes": { "HumanSession": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Sessão humana validada pelo emissor e pelo servidor; assinatura isolada não prova classe de ator." }, "ApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "Opaque", "description": "Chave nova limitada a apps e permissões. Chaves legadas não são aceitas no namespace novo." } }, "schemas": { "RequestId": { "type": "string", "maxLength": 36, "pattern": "^req_[a-f0-9]{32}$" }, "IfMatch": { "type": "string", "maxLength": 38, "pattern": "^\"[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}\"$" }, "Me": { "type": "object", "additionalProperties": false, "properties": { "userId": { "type": "string", "format": "uuid" }, "displayName": { "anyOf": [ { "type": "string", "maxLength": 100, "pattern": "^[^\\u0000-\\u001f\\u007f]*$" }, { "type": "null" } ] }, "photoUrl": { "anyOf": [ { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)" }, { "type": "null" } ] }, "actorType": { "enum": [ "human", "api_key", "oauth" ] }, "revision": { "type": "string", "format": "uuid" } }, "required": [ "userId", "displayName", "photoUrl", "actorType", "revision" ] }, "MeEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Me" }, "meta": { "type": "object", "additionalProperties": false, "properties": { "requestId": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "requestId" ] } }, "required": [ "data", "meta" ] }, "ErrorEnvelope": { "type": "object", "additionalProperties": false, "properties": { "error": { "type": "object", "additionalProperties": false, "properties": { "code": { "enum": [ "invalid_request", "validation_failed", "unauthenticated", "insufficient_permission", "not_found", "resource_conflict", "idempotency_conflict", "operation_in_progress", "secret_not_replayable", "invalid_cursor", "revision_conflict", "precondition_required", "payload_too_large", "unsupported_media_type", "rate_limited", "feature_disabled", "resource_expired", "dependency_unavailable", "internal_error" ] }, "message": { "type": "string", "maxLength": 1000, "minLength": 1 }, "details": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "maxLength": 200 }, "reason": { "type": "string", "maxLength": 100 }, "permission": { "type": "string", "maxLength": 100 } }, "required": [] }, "maxItems": 50 }, "requestId": { "$ref": "#/components/schemas/RequestId" }, "documentationUrl": { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)" }, "resource": { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "maxLength": 100, "minLength": 1 }, "id": { "type": "string", "maxLength": 500, "minLength": 1, "pattern": "^[^/\\u0000-\\u001f\\u007f]+$" } }, "required": [ "type", "id" ] } }, "required": [ "code", "message", "requestId", "documentationUrl" ] } }, "required": [ "error" ] }, "IdempotencyKey": { "type": "string", "maxLength": 36, "pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$" }, "MePatch": { "type": "object", "additionalProperties": false, "properties": { "displayName": { "type": "string", "maxLength": 100, "minLength": 1 }, "photoUrl": { "anyOf": [ { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)" }, { "type": "null" } ] } }, "required": [], "minProperties": 1 }, "Preferences": { "type": "object", "additionalProperties": false, "properties": { "selectedAppId": { "anyOf": [ { "type": "string", "maxLength": 500, "minLength": 1, "pattern": "^[^/\\u0000-\\u001f\\u007f]+$" }, { "type": "null" } ] }, "theme": { "enum": [ "light", "dark", "system" ] }, "revision": { "type": "string", "format": "uuid" } }, "required": [ "selectedAppId", "theme", "revision" ] }, "PreferencesEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Preferences" }, "meta": { "type": "object", "additionalProperties": false, "properties": { "requestId": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "requestId" ] } }, "required": [ "data", "meta" ] }, "PreferencesPatch": { "type": "object", "additionalProperties": false, "properties": { "selectedAppId": { "anyOf": [ { "type": "string", "maxLength": 500, "minLength": 1, "pattern": "^[^/\\u0000-\\u001f\\u007f]+$" }, { "type": "null" } ] }, "theme": { "enum": [ "light", "dark", "system" ] } }, "required": [], "minProperties": 1 }, "Cursor": { "type": "string", "maxLength": 2048, "pattern": "^c1\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$" }, "Pagination": { "type": "object", "additionalProperties": false, "properties": { "nextCursor": { "anyOf": [ { "$ref": "#/components/schemas/Cursor" }, { "type": "null" } ] }, "hasMore": { "type": "boolean" } }, "required": [ "nextCursor", "hasMore" ] }, "ApiKeyListEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 100, "minLength": 1 }, "prefix": { "type": "string", "maxLength": 30, "pattern": "^agl_(live|test)_[A-Za-z0-9_-]{4,12}$" }, "appIds": { "type": "array", "items": { "type": "string", "maxLength": 500, "minLength": 1, "pattern": "^[^/\\u0000-\\u001f\\u007f]+$" }, "maxItems": 100, "minItems": 1, "uniqueItems": true }, "permissions": { "type": "array", "items": { "enum": [ "analytics:read", "apps:delete", "apps:read", "apps:update", "assets:create", "assets:delete", "assets:read", "batches:create", "batches:read", "campaigns:create", "campaigns:delete", "campaigns:read", "campaigns:update", "capabilities:read", "dns:create", "dns:delete", "dns:read", "dns:update", "domains:create", "domains:delete", "domains:read", "domains:verify", "exports:create", "exports:read", "folders:create", "folders:delete", "folders:read", "folders:update", "identity:read", "imports:commit", "imports:create", "imports:read", "imports:validate", "link_history:read", "links:create", "links:delete", "links:preview", "links:read", "links:resync", "links:update", "links:validate", "native_config:read", "native_config:update", "operations:cancel", "operations:read", "qr_codes:create", "qr_codes:delete", "qr_codes:read", "qr_codes:update", "recovery_config:read", "recovery_config:update", "routing_rules:read", "routing_rules:update", "tags:create", "tags:delete", "tags:read", "tags:update", "template_bindings:read", "template_bindings:update", "templates:create", "templates:preview", "templates:publish", "templates:read", "templates:retry", "templates:snapshot", "templates:update", "templates:validate", "usage:read", "web_config:read", "web_config:update", "webhooks:create", "webhooks:delete", "webhooks:read", "webhooks:retry", "webhooks:rotate_secret", "webhooks:test", "webhooks:update" ] }, "maxItems": 100, "minItems": 1, "uniqueItems": true }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "revision": { "type": "string", "format": "uuid" } }, "required": [ "id", "name", "prefix", "appIds", "permissions", "expiresAt", "createdAt", "lastUsedAt", "revokedAt", "revision" ] }, "maxItems": 100 }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "type": "object", "additionalProperties": false, "properties": { "requestId": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "requestId" ] } }, "required": [ "data", "pagination", "meta" ] }, "ApiKeyCreate": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 100, "minLength": 1 }, "appIds": { "type": "array", "items": { "type": "string", "maxLength": 500, "minLength": 1, "pattern": "^[^/\\u0000-\\u001f\\u007f]+$" }, "maxItems": 100, "minItems": 1, "uniqueItems": true }, "permissions": { "type": "array", "items": { "enum": [ "analytics:read", "apps:delete", "apps:read", "apps:update", "assets:create", "assets:delete", "assets:read", "batches:create", "batches:read", "campaigns:create", "campaigns:delete", "campaigns:read", "campaigns:update", "capabilities:read", "dns:create", "dns:delete", "dns:read", "dns:update", "domains:create", "domains:delete", "domains:read", "domains:verify", "exports:create", "exports:read", "folders:create", "folders:delete", "folders:read", "folders:update", "identity:read", "imports:commit", "imports:create", "imports:read", "imports:validate", "link_history:read", "links:create", "links:delete", "links:preview", "links:read", "links:resync", "links:update", "links:validate", "native_config:read", "native_config:update", "operations:cancel", "operations:read", "qr_codes:create", "qr_codes:delete", "qr_codes:read", "qr_codes:update", "recovery_config:read", "recovery_config:update", "routing_rules:read", "routing_rules:update", "tags:create", "tags:delete", "tags:read", "tags:update", "template_bindings:read", "template_bindings:update", "templates:create", "templates:preview", "templates:publish", "templates:read", "templates:retry", "templates:snapshot", "templates:update", "templates:validate", "usage:read", "web_config:read", "web_config:update", "webhooks:create", "webhooks:delete", "webhooks:read", "webhooks:retry", "webhooks:rotate_secret", "webhooks:test", "webhooks:update" ] }, "maxItems": 100, "minItems": 1, "uniqueItems": true }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "name", "appIds", "permissions" ] }, "ApiKeyIssuedEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "object", "additionalProperties": false, "properties": { "key": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 100, "minLength": 1 }, "prefix": { "type": "string", "maxLength": 30, "pattern": "^agl_(live|test)_[A-Za-z0-9_-]{4,12}$" }, "appIds": { "type": "array", "items": { "type": "string", "maxLength": 500, "minLength": 1, "pattern": "^[^/\\u0000-\\u001f\\u007f]+$" }, "maxItems": 100, "minItems": 1, "uniqueItems": true }, "permissions": { "type": "array", "items": { "enum": [ "analytics:read", "apps:delete", "apps:read", "apps:update", "assets:create", "assets:delete", "assets:read", "batches:create", "batches:read", "campaigns:create", "campaigns:delete", "campaigns:read", "campaigns:update", "capabilities:read", "dns:create", "dns:delete", "dns:read", "dns:update", "domains:create", "domains:delete", "domains:read", "domains:verify", "exports:create", "exports:read", "folders:create", "folders:delete", "folders:read", "folders:update", "identity:read", "imports:commit", "imports:create", "imports:read", "imports:validate", "link_history:read", "links:create", "links:delete", "links:preview", "links:read", "links:resync", "links:update", "links:validate", "native_config:read", "native_config:update", "operations:cancel", "operations:read", "qr_codes:create", "qr_codes:delete", "qr_codes:read", "qr_codes:update", "recovery_config:read", "recovery_config:update", "routing_rules:read", "routing_rules:update", "tags:create", "tags:delete", "tags:read", "tags:update", "template_bindings:read", "template_bindings:update", "templates:create", "templates:preview", "templates:publish", "templates:read", "templates:retry", "templates:snapshot", "templates:update", "templates:validate", "usage:read", "web_config:read", "web_config:update", "webhooks:create", "webhooks:delete", "webhooks:read", "webhooks:retry", "webhooks:rotate_secret", "webhooks:test", "webhooks:update" ] }, "maxItems": 100, "minItems": 1, "uniqueItems": true }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "revision": { "type": "string", "format": "uuid" } }, "required": [ "id", "name", "prefix", "appIds", "permissions", "expiresAt", "createdAt", "lastUsedAt", "revokedAt", "revision" ] }, "secret": { "type": "string", "maxLength": 52, "pattern": "^agl_(live|test)_[A-Za-z0-9_-]{43}$" } }, "required": [ "key", "secret" ] }, "meta": { "type": "object", "additionalProperties": false, "properties": { "requestId": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "requestId" ] } }, "required": [ "data", "meta" ] }, "Revision": { "type": "string", "format": "uuid" }, "ApiKeyEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 100, "minLength": 1 }, "prefix": { "type": "string", "maxLength": 30, "pattern": "^agl_(live|test)_[A-Za-z0-9_-]{4,12}$" }, "appIds": { "type": "array", "items": { "type": "string", "maxLength": 500, "minLength": 1, "pattern": "^[^/\\u0000-\\u001f\\u007f]+$" }, "maxItems": 100, "minItems": 1, "uniqueItems": true }, "permissions": { "type": "array", "items": { "enum": [ "analytics:read", "apps:delete", "apps:read", "apps:update", "assets:create", "assets:delete", "assets:read", "batches:create", "batches:read", "campaigns:create", "campaigns:delete", "campaigns:read", "campaigns:update", "capabilities:read", "dns:create", "dns:delete", "dns:read", "dns:update", "domains:create", "domains:delete", "domains:read", "domains:verify", "exports:create", "exports:read", "folders:create", "folders:delete", "folders:read", "folders:update", "identity:read", "imports:commit", "imports:create", "imports:read", "imports:validate", "link_history:read", "links:create", "links:delete", "links:preview", "links:read", "links:resync", "links:update", "links:validate", "native_config:read", "native_config:update", "operations:cancel", "operations:read", "qr_codes:create", "qr_codes:delete", "qr_codes:read", "qr_codes:update", "recovery_config:read", "recovery_config:update", "routing_rules:read", "routing_rules:update", "tags:create", "tags:delete", "tags:read", "tags:update", "template_bindings:read", "template_bindings:update", "templates:create", "templates:preview", "templates:publish", "templates:read", "templates:retry", "templates:snapshot", "templates:update", "templates:validate", "usage:read", "web_config:read", "web_config:update", "webhooks:create", "webhooks:delete", "webhooks:read", "webhooks:retry", "webhooks:rotate_secret", "webhooks:test", "webhooks:update" ] }, "maxItems": 100, "minItems": 1, "uniqueItems": true }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "revision": { "type": "string", "format": "uuid" } }, "required": [ "id", "name", "prefix", "appIds", "permissions", "expiresAt", "createdAt", "lastUsedAt", "revokedAt", "revision" ] }, "meta": { "type": "object", "additionalProperties": false, "properties": { "requestId": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "requestId" ] } }, "required": [ "data", "meta" ] }, "ApiKeyPatch": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 100, "minLength": 1 }, "appIds": { "type": "array", "items": { "type": "string", "maxLength": 500, "minLength": 1, "pattern": "^[^/\\u0000-\\u001f\\u007f]+$" }, "maxItems": 100, "minItems": 1, "uniqueItems": true }, "permissions": { "type": "array", "items": { "enum": [ "analytics:read", "apps:delete", "apps:read", "apps:update", "assets:create", "assets:delete", "assets:read", "batches:create", "batches:read", "campaigns:create", "campaigns:delete", "campaigns:read", "campaigns:update", "capabilities:read", "dns:create", "dns:delete", "dns:read", "dns:update", "domains:create", "domains:delete", "domains:read", "domains:verify", "exports:create", "exports:read", "folders:create", "folders:delete", "folders:read", "folders:update", "identity:read", "imports:commit", "imports:create", "imports:read", "imports:validate", "link_history:read", "links:create", "links:delete", "links:preview", "links:read", "links:resync", "links:update", "links:validate", "native_config:read", "native_config:update", "operations:cancel", "operations:read", "qr_codes:create", "qr_codes:delete", "qr_codes:read", "qr_codes:update", "recovery_config:read", "recovery_config:update", "routing_rules:read", "routing_rules:update", "tags:create", "tags:delete", "tags:read", "tags:update", "template_bindings:read", "template_bindings:update", "templates:create", "templates:preview", "templates:publish", "templates:read", "templates:retry", "templates:snapshot", "templates:update", "templates:validate", "usage:read", "web_config:read", "web_config:update", "webhooks:create", "webhooks:delete", "webhooks:read", "webhooks:retry", "webhooks:rotate_secret", "webhooks:test", "webhooks:update" ] }, "maxItems": 100, "minItems": 1, "uniqueItems": true }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [], "minProperties": 1 }, "OpaqueId": { "type": "string", "maxLength": 500, "minLength": 1, "pattern": "^[^/\\u0000-\\u001f\\u007f]+$" }, "Domain": { "type": "string", "maxLength": 253, "pattern": "^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$" }, "LinkId": { "type": "string", "maxLength": 500, "pattern": "^[a-z0-9.-]+~-(?:(?!~-)[A-Za-z0-9._~-])*~-(?:(?!~-)[A-Za-z0-9._~-])+$" }, "AnalyticsInstant": { "type": "string", "format": "date-time", "pattern": "T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?(?:[Zz]|[+-]\\d{2}:\\d{2})$" }, "LinkLifecycle": { "type": "object", "additionalProperties": false, "properties": { "archived": { "type": "boolean" }, "paused": { "type": "boolean" }, "startsAt": { "anyOf": [ { "$ref": "#/components/schemas/AnalyticsInstant" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "$ref": "#/components/schemas/AnalyticsInstant" }, { "type": "null" } ] }, "fallbackUrl": { "anyOf": [ { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)" }, { "type": "null" } ] } }, "required": [ "archived", "paused", "startsAt", "expiresAt", "fallbackUrl" ] }, "UtmParameters": { "type": "object", "additionalProperties": false, "properties": { "utm_source": { "type": "string", "maxLength": 200, "minLength": 1, "pattern": "^[^\\u0000-\\u001f\\u007f]+$" }, "utm_medium": { "type": "string", "maxLength": 200, "minLength": 1, "pattern": "^[^\\u0000-\\u001f\\u007f]+$" }, "utm_campaign": { "type": "string", "maxLength": 200, "minLength": 1, "pattern": "^[^\\u0000-\\u001f\\u007f]+$" }, "utm_term": { "type": "string", "maxLength": 200, "minLength": 1, "pattern": "^[^\\u0000-\\u001f\\u007f]+$" }, "utm_content": { "type": "string", "maxLength": 200, "minLength": 1, "pattern": "^[^\\u0000-\\u001f\\u007f]+$" } }, "required": [] }, "JsonValue": { "anyOf": [ { "type": [ "string", "number", "boolean", "null" ] }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] }, "Parameters": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "$comment": "Validar profundidade <= 5 e JSON UTF-8 <= 16 KiB no validador semântico." }, "LinkListEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "$ref": "#/components/schemas/LinkId" }, "appId": { "type": "string", "maxLength": 500, "minLength": 1, "pattern": "^[^/\\u0000-\\u001f\\u007f]+$" }, "domain": { "$ref": "#/components/schemas/Domain" }, "prefix": { "type": "string", "maxLength": 200, "pattern": "^(?!.*~-)(?!\\.{1,2}$)[A-Za-z0-9._~-]*$" }, "slug": { "type": "string", "maxLength": 200, "pattern": "^(?!.*~-)(?!\\.{1,2}$)[A-Za-z0-9._~-]*$", "minLength": 1 }, "url": { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)" }, "folderId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "campaignId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "lifecycle": { "$ref": "#/components/schemas/LinkLifecycle" }, "utm": { "$ref": "#/components/schemas/UtmParameters" }, "title": { "anyOf": [ { "type": "string", "maxLength": 1000, "pattern": "^[^\\u0000-\\u001f\\u007f]*$" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 4000, "pattern": "^[^\\u0000-\\u001f\\u007f]*$" }, { "type": "null" } ] }, "imageUrl": { "anyOf": [ { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)" }, { "type": "null" } ] }, "desktopUrl": { "anyOf": [ { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)" }, { "type": "null" } ] }, "playStoreUrl": { "anyOf": [ { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)" }, { "type": "null" } ] }, "appStoreUrl": { "anyOf": [ { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)" }, { "type": "null" } ] }, "appPath": { "anyOf": [ { "type": "string", "maxLength": 2048, "minLength": 1, "pattern": "^(?!/)(?!.*[?#\\\\])(?!.*(?:^|/)\\.{1,2}(?:/|$))[^/]+(?:/[^/]+)*$" }, { "type": "null" } ] }, "parameters": { "$ref": "#/components/schemas/Parameters" }, "webOnly": { "type": "boolean" }, "behavior": { "enum": [ "manual", "automatic", "intelligent" ] }, "group": { "enum": [ "main", "operational" ] }, "templateData": { "type": "object", "additionalProperties": { "type": [ "string", "number", "boolean" ] } }, "templateSelection": { "type": "object", "additionalProperties": false, "properties": { "android": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "mode": { "const": "inherit" } }, "required": [ "mode" ] }, { "type": "object", "additionalProperties": false, "properties": { "mode": { "const": "official" } }, "required": [ "mode" ] }, { "type": "object", "additionalProperties": false, "properties": { "mode": { "const": "custom" }, "templateId": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1 } }, "required": [ "mode", "templateId", "version" ] } ] }, "ios": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "mode": { "const": "inherit" } }, "required": [ "mode" ] }, { "type": "object", "additionalProperties": false, "properties": { "mode": { "const": "official" } }, "required": [ "mode" ] }, { "type": "object", "additionalProperties": false, "properties": { "mode": { "const": "custom" }, "templateId": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1 } }, "required": [ "mode", "templateId", "version" ] } ] }, "recovery": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "mode": { "const": "inherit" } }, "required": [ "mode" ] }, { "type": "object", "additionalProperties": false, "properties": { "mode": { "const": "official" } }, "required": [ "mode" ] }, { "type": "object", "additionalProperties": false, "properties": { "mode": { "const": "custom" }, "templateId": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1 } }, "required": [ "mode", "templateId", "version" ] } ] } }, "required": [] }, "origin": { "enum": [ "dashboard", "api" ] }, "revision": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "publication": { "type": "object", "additionalProperties": false, "properties": { "status": { "enum": [ "pending", "synced", "failed" ] }, "desiredRevision": { "type": "string", "format": "uuid" }, "confirmedRevision": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "status", "desiredRevision", "confirmedRevision", "updatedAt" ] }, "tagIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 20, "uniqueItems": true }, "state": { "enum": [ "active", "paused", "scheduled", "expired" ] } }, "required": [ "id", "appId", "domain", "prefix", "slug", "url", "title", "desktopUrl", "group", "origin", "revision", "createdAt", "updatedAt", "publication" ] }, "maxItems": 100 }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "type": "object", "additionalProperties": false, "properties": { "requestId": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "requestId" ] } }, "required": [ "data", "pagination", "meta" ] }, "LinkCreate": { "type": "object", "additionalProperties": false, "properties": { "appId": { "type": "string", "maxLength": 500, "minLength": 1, "pattern": "^[^/\\u0000-\\u001f\\u007f]+$" }, "domain": { "$ref": "#/components/schemas/Domain" }, "prefix": { "type": "string", "maxLength": 200, "pattern": "^(?!.*~-)(?!\\.{1,2}$)[A-Za-z0-9._~-]*$" }, "slug": { "type": "string", "maxLength": 200, "pattern": "^(?!.*~-)(?!\\.{1,2}$)[A-Za-z0-9._~-]*$", "minLength": 1 }, "folderId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "campaignId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "lifecycle": { "$ref": "#/components/schemas/LinkLifecycle" }, "utm": { "$ref": "#/components/schemas/UtmParameters" }, "title": { "anyOf": [ { "type": "string", "maxLength": 1000, "pattern": "^[^\\u0000-\\u001f\\u007f]*$" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 4000, "pattern": "^[^\\u0000-\\u001f\\u007f]*$" }, { "type": "null" } ] }, "imageUrl": { "anyOf": [ { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)" }, { "type": "null" } ] }, "desktopUrl": { "anyOf": [ { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)" }, { "type": "null" } ] }, "playStoreUrl": { "anyOf": [ { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)" }, { "type": "null" } ] }, "appStoreUrl": { "anyOf": [ { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)" }, { "type": "null" } ] }, "appPath": { "anyOf": [ { "type": "string", "maxLength": 2048, "minLength": 1, "pattern": "^(?!/)(?!.*[?#\\\\])(?!.*(?:^|/)\\.{1,2}(?:/|$))[^/]+(?:/[^/]+)*$" }, { "type": "null" } ] }, "parameters": { "$ref": "#/components/schemas/Parameters" }, "webOnly": { "type": "boolean" }, "behavior": { "enum": [ "manual", "automatic", "intelligent" ] }, "group": { "enum": [ "main", "operational" ] }, "templateData": { "type": "object", "additionalProperties": { "type": [ "string", "number", "boolean" ] } }, "templateSelection": { "type": "object", "additionalProperties": false, "properties": { "android": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "mode": { "const": "inherit" } }, "required": [ "mode" ] }, { "type": "object", "additionalProperties": false, "properties": { "mode": { "const": "official" } }, "required": [ "mode" ] }, { "type": "object", "additionalProperties": false, "properties": { "mode": { "const": "custom" }, "templateId": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1 } }, "required": [ "mode", "templateId", "version" ] } ] }, "ios": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "mode": { "const": "inherit" } }, "required": [ "mode" ] }, { "type": "object", "additionalProperties": false, "properties": { "mode": { "const": "official" } }, "required": [ "mode" ] }, { "type": "object", "additionalProperties": false, "properties": { "mode": { "const": "custom" }, "templateId": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1 } }, "required": [ "mode", "templateId", "version" ] } ] }, "recovery": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "mode": { "const": "inherit" } }, "required": [ "mode" ] }, { "type": "object", "additionalProperties": false, "properties": { "mode": { "const": "official" } }, "required": [ "mode" ] }, { "type": "object", "additionalProperties": false, "properties": { "mode": { "const": "custom" }, "templateId": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1 } }, "required": [ "mode", "templateId", "version" ] } ] } }, "required": [] } }, "required": [ "appId", "domain", "slug" ] }, "LinkEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "object", "additionalProperties": false, "properties": { "id": { "$ref": "#/components/schemas/LinkId" }, "appId": { "type": "string", "maxLength": 500, "minLength": 1, "pattern": "^[^/\\u0000-\\u001f\\u007f]+$" }, "domain": { "$ref": "#/components/schemas/Domain" }, "prefix": { "type": "string", "maxLength": 200, "pattern": "^(?!.*~-)(?!\\.{1,2}$)[A-Za-z0-9._~-]*$" }, "slug": { "type": "string", "maxLength": 200, "pattern": "^(?!.*~-)(?!\\.{1,2}$)[A-Za-z0-9._~-]*$", "minLength": 1 }, "url": { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)" }, "folderId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "campaignId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "lifecycle": { "$ref": "#/components/schemas/LinkLifecycle" }, "utm": { "$ref": "#/components/schemas/UtmParameters" }, "title": { "anyOf": [ { "type": "string", "maxLength": 1000, "pattern": "^[^\\u0000-\\u001f\\u007f]*$" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 4000, "pattern": "^[^\\u0000-\\u001f\\u007f]*$" }, { "type": "null" } ] }, "imageUrl": { "anyOf": [ { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)" }, { "type": "null" } ] }, "desktopUrl": { "anyOf": [ { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)" }, { "type": "null" } ] }, "playStoreUrl": { "anyOf": [ { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)" }, { "type": "null" } ] }, "appStoreUrl": { "anyOf": [ { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)" }, { "type": "null" } ] }, "appPath": { "anyOf": [ { "type": "string", "maxLength": 2048, "minLength": 1, "pattern": "^(?!/)(?!.*[?#\\\\])(?!.*(?:^|/)\\.{1,2}(?:/|$))[^/]+(?:/[^/]+)*$" }, { "type": "null" } ] }, "parameters": { "$ref": "#/components/schemas/Parameters" }, "webOnly": { "type": "boolean" }, "behavior": { "enum": [ "manual", "automatic", "intelligent" ] }, "group": { "enum": [ "main", "operational" ] }, "templateData": { "type": "object", "additionalProperties": { "type": [ "string", "number", "boolean" ] } }, "templateSelection": { "type": "object", "additionalProperties": false, "properties": { "android": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "mode": { "const": "inherit" } }, "required": [ "mode" ] }, { "type": "object", "additionalProperties": false, "properties": { "mode": { "const": "official" } }, "required": [ "mode" ] }, { "type": "object", "additionalProperties": false, "properties": { "mode": { "const": "custom" }, "templateId": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1 } }, "required": [ "mode", "templateId", "version" ] } ] }, "ios": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "mode": { "const": "inherit" } }, "required": [ "mode" ] }, { "type": "object", "additionalProperties": false, "properties": { "mode": { "const": "official" } }, "required": [ "mode" ] }, { "type": "object", "additionalProperties": false, "properties": { "mode": { "const": "custom" }, "templateId": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1 } }, "required": [ "mode", "templateId", "version" ] } ] }, "recovery": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "mode": { "const": "inherit" } }, "required": [ "mode" ] }, { "type": "object", "additionalProperties": false, "properties": { "mode": { "const": "official" } }, "required": [ "mode" ] }, { "type": "object", "additionalProperties": false, "properties": { "mode": { "const": "custom" }, "templateId": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1 } }, "required": [ "mode", "templateId", "version" ] } ] } }, "required": [] }, "origin": { "enum": [ "dashboard", "api" ] }, "revision": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "publication": { "type": "object", "additionalProperties": false, "properties": { "status": { "enum": [ "pending", "synced", "failed" ] }, "desiredRevision": { "type": "string", "format": "uuid" }, "confirmedRevision": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "status", "desiredRevision", "confirmedRevision", "updatedAt" ] }, "tagIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 20, "uniqueItems": true }, "state": { "enum": [ "active", "paused", "scheduled", "expired" ] } }, "required": [ "id", "appId", "domain", "prefix", "slug", "url", "title", "desktopUrl", "group", "origin", "revision", "createdAt", "updatedAt", "publication" ] }, "meta": { "type": "object", "additionalProperties": false, "properties": { "requestId": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "requestId" ] } }, "required": [ "data", "meta" ] }, "LinkPatch": { "type": "object", "additionalProperties": false, "properties": { "folderId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "campaignId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "lifecycle": { "$ref": "#/components/schemas/LinkLifecycle" }, "utm": { "$ref": "#/components/schemas/UtmParameters" }, "title": { "anyOf": [ { "type": "string", "maxLength": 1000, "pattern": "^[^\\u0000-\\u001f\\u007f]*$" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 4000, "pattern": "^[^\\u0000-\\u001f\\u007f]*$" }, { "type": "null" } ] }, "imageUrl": { "anyOf": [ { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)" }, { "type": "null" } ] }, "desktopUrl": { "anyOf": [ { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)" }, { "type": "null" } ] }, "playStoreUrl": { "anyOf": [ { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)" }, { "type": "null" } ] }, "appStoreUrl": { "anyOf": [ { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)" }, { "type": "null" } ] }, "appPath": { "anyOf": [ { "type": "string", "maxLength": 2048, "minLength": 1, "pattern": "^(?!/)(?!.*[?#\\\\])(?!.*(?:^|/)\\.{1,2}(?:/|$))[^/]+(?:/[^/]+)*$" }, { "type": "null" } ] }, "parameters": { "$ref": "#/components/schemas/Parameters" }, "webOnly": { "type": "boolean" }, "behavior": { "enum": [ "manual", "automatic", "intelligent" ] }, "group": { "enum": [ "main", "operational" ] }, "templateData": { "type": "object", "additionalProperties": { "type": [ "string", "number", "boolean" ] } }, "templateSelection": { "type": "object", "additionalProperties": false, "properties": { "android": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "mode": { "const": "inherit" } }, "required": [ "mode" ] }, { "type": "object", "additionalProperties": false, "properties": { "mode": { "const": "official" } }, "required": [ "mode" ] }, { "type": "object", "additionalProperties": false, "properties": { "mode": { "const": "custom" }, "templateId": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1 } }, "required": [ "mode", "templateId", "version" ] } ] }, "ios": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "mode": { "const": "inherit" } }, "required": [ "mode" ] }, { "type": "object", "additionalProperties": false, "properties": { "mode": { "const": "official" } }, "required": [ "mode" ] }, { "type": "object", "additionalProperties": false, "properties": { "mode": { "const": "custom" }, "templateId": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1 } }, "required": [ "mode", "templateId", "version" ] } ] }, "recovery": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "mode": { "const": "inherit" } }, "required": [ "mode" ] }, { "type": "object", "additionalProperties": false, "properties": { "mode": { "const": "official" } }, "required": [ "mode" ] }, { "type": "object", "additionalProperties": false, "properties": { "mode": { "const": "custom" }, "templateId": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1 } }, "required": [ "mode", "templateId", "version" ] } ] } }, "required": [] } }, "required": [], "minProperties": 1 }, "Operation": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "maxLength": 500, "minLength": 1, "pattern": "^[^/\\u0000-\\u001f\\u007f]+$" }, "appId": { "anyOf": [ { "type": "string", "maxLength": 500, "minLength": 1, "pattern": "^[^/\\u0000-\\u001f\\u007f]+$" }, { "type": "null" } ] }, "type": { "type": "string", "maxLength": 100, "minLength": 1 }, "status": { "enum": [ "queued", "running", "succeeded", "partially_succeeded", "failed", "cancel_requested", "cancelled" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "revision": { "type": "string", "format": "uuid" }, "result": { "type": [ "object", "null" ], "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } }, "error": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "code": { "enum": [ "invalid_request", "validation_failed", "unauthenticated", "insufficient_permission", "not_found", "resource_conflict", "idempotency_conflict", "operation_in_progress", "secret_not_replayable", "invalid_cursor", "revision_conflict", "precondition_required", "payload_too_large", "unsupported_media_type", "rate_limited", "feature_disabled", "resource_expired", "dependency_unavailable", "internal_error" ] }, "message": { "type": "string", "maxLength": 1000, "minLength": 1 }, "details": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "maxLength": 200 }, "reason": { "type": "string", "maxLength": 100 }, "permission": { "type": "string", "maxLength": 100 } }, "required": [] }, "maxItems": 50 }, "requestId": { "$ref": "#/components/schemas/RequestId" }, "documentationUrl": { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)" }, "resource": { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "maxLength": 100, "minLength": 1 }, "id": { "type": "string", "maxLength": 500, "minLength": 1, "pattern": "^[^/\\u0000-\\u001f\\u007f]+$" } }, "required": [ "type", "id" ] } }, "required": [ "code", "message", "requestId", "documentationUrl" ] }, { "type": "null" } ] } }, "required": [ "id", "appId", "type", "status", "createdAt", "updatedAt", "revision", "result", "error" ] }, "OperationEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Operation" }, "meta": { "type": "object", "additionalProperties": false, "properties": { "requestId": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "requestId" ] } }, "required": [ "data", "meta" ] }, "ApiKeyRotate": { "type": "object", "additionalProperties": false, "properties": { "overlapSeconds": { "type": "integer", "minimum": 0, "maximum": 86400, "default": 0 } }, "required": [] }, "Permission": { "enum": [ "analytics:read", "api_keys:create", "api_keys:delete", "api_keys:read", "api_keys:rotate", "api_keys:update", "apps:create", "apps:delete", "apps:read", "apps:update", "assets:create", "assets:delete", "assets:read", "audit_events:read", "batches:create", "batches:read", "campaigns:create", "campaigns:delete", "campaigns:read", "campaigns:update", "capabilities:read", "dns:create", "dns:delete", "dns:read", "dns:update", "domains:create", "domains:delete", "domains:read", "domains:verify", "exports:create", "exports:read", "folders:create", "folders:delete", "folders:read", "folders:update", "identity:read", "imports:commit", "imports:create", "imports:read", "imports:validate", "link_history:read", "links:create", "links:delete", "links:preview", "links:read", "links:resync", "links:update", "links:validate", "native_config:read", "native_config:update", "operations:cancel", "operations:read", "preferences:read", "preferences:update", "profile:update", "qr_codes:create", "qr_codes:delete", "qr_codes:read", "qr_codes:update", "recovery_config:read", "recovery_config:update", "requests:read", "routing_rules:read", "routing_rules:update", "tags:create", "tags:delete", "tags:read", "tags:update", "template_bindings:read", "template_bindings:update", "templates:create", "templates:preview", "templates:publish", "templates:read", "templates:retry", "templates:snapshot", "templates:update", "templates:validate", "usage:read", "web_config:read", "web_config:update", "webhooks:create", "webhooks:delete", "webhooks:read", "webhooks:retry", "webhooks:rotate_secret", "webhooks:test", "webhooks:update" ] }, "CapabilitiesEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "object", "additionalProperties": false, "properties": { "environment": { "enum": [ "local", "staging", "production" ] }, "operations": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "operationId": { "type": "string", "maxLength": 100 }, "permission": { "$ref": "#/components/schemas/Permission" } }, "required": [ "operationId", "permission" ] }, "maxItems": 143 }, "oauth": { "const": false }, "mcp": { "const": false } }, "required": [ "environment", "operations", "oauth", "mcp" ] }, "meta": { "type": "object", "additionalProperties": false, "properties": { "requestId": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "requestId" ] } }, "required": [ "data", "meta" ] }, "UsageEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "object", "additionalProperties": false, "properties": { "appId": { "type": "string", "maxLength": 500, "minLength": 1, "pattern": "^[^/\\u0000-\\u001f\\u007f]+$" }, "scope": { "const": "credential" }, "windowSeconds": { "const": 60 }, "limits": { "type": "object", "additionalProperties": false, "properties": { "ingress": { "type": "integer" }, "read": { "type": "integer" }, "write": { "type": "integer" } }, "required": [ "ingress", "read", "write" ] }, "usage": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "sharedLimits": { "type": "object", "additionalProperties": false, "properties": { "owner": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 1 } }, "app": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 1 } } }, "required": [ "owner", "app" ] }, "sharedUsage": { "type": "object", "additionalProperties": false, "properties": { "owner": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "app": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } } }, "required": [ "owner", "app" ] } }, "required": [ "appId", "scope", "windowSeconds", "limits", "usage", "sharedLimits", "sharedUsage" ] }, "meta": { "type": "object", "additionalProperties": false, "properties": { "requestId": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "requestId" ] } }, "required": [ "data", "meta" ] }, "AuditEvent": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "at": { "type": "string", "format": "date-time" }, "requestId": { "$ref": "#/components/schemas/RequestId" }, "actorType": { "enum": [ "human", "api_key" ] }, "credentialId": { "type": "string", "maxLength": 500, "minLength": 1, "pattern": "^[^/\\u0000-\\u001f\\u007f]+$" }, "operationId": { "type": "string", "maxLength": 100 }, "resourceId": { "anyOf": [ { "type": "string", "maxLength": 500, "minLength": 1, "pattern": "^[^/\\u0000-\\u001f\\u007f]+$" }, { "type": "null" } ] }, "appId": { "anyOf": [ { "type": "string", "maxLength": 500, "minLength": 1, "pattern": "^[^/\\u0000-\\u001f\\u007f]+$" }, { "type": "null" } ] }, "revision": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] } }, "required": [ "id", "at", "requestId", "actorType", "credentialId", "operationId", "resourceId", "appId", "revision" ] }, "AuditEventListEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEvent" }, "maxItems": 100 }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "type": "object", "additionalProperties": false, "properties": { "requestId": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "requestId" ] } }, "required": [ "data", "pagination", "meta" ] }, "RequestRecord": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "at": { "type": "string", "format": "date-time" }, "requestId": { "$ref": "#/components/schemas/RequestId" }, "actorType": { "enum": [ "human", "api_key" ] }, "credentialId": { "type": "string", "maxLength": 500, "minLength": 1, "pattern": "^[^/\\u0000-\\u001f\\u007f]+$" }, "operationId": { "type": "string", "maxLength": 100 }, "status": { "type": "integer", "minimum": 100, "maximum": 599 }, "durationMs": { "type": "integer", "minimum": 0 }, "errorCode": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] } }, "required": [ "id", "at", "requestId", "actorType", "credentialId", "operationId", "status", "durationMs", "errorCode" ] }, "RequestListEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RequestRecord" }, "maxItems": 100 }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "type": "object", "additionalProperties": false, "properties": { "requestId": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "requestId" ] } }, "required": [ "data", "pagination", "meta" ] }, "EmptyObject": { "type": "object", "additionalProperties": false, "properties": {}, "required": [] }, "AppId": { "type": "string", "maxLength": 200, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._~-]*$" }, "App": { "type": "object", "additionalProperties": false, "properties": { "id": { "$ref": "#/components/schemas/AppId" }, "name": { "type": "string", "maxLength": 4096, "pattern": "^[^\\u0000-\\u001f\\u007f]*$" }, "defaultDomain": { "anyOf": [ { "$ref": "#/components/schemas/Domain" }, { "type": "null" } ] }, "desktopUrl": { "anyOf": [ { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)" }, { "type": "null" } ] }, "playStoreUrl": { "anyOf": [ { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)" }, { "type": "null" } ] }, "appStoreUrl": { "anyOf": [ { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)" }, { "type": "null" } ] }, "scheme": { "anyOf": [ { "type": "string", "maxLength": 100, "pattern": "^[^\\u0000-\\u001f\\u007f]*$" }, { "type": "null" } ] }, "androidPackage": { "anyOf": [ { "type": "string", "maxLength": 255, "pattern": "^[^\\u0000-\\u001f\\u007f]*$" }, { "type": "null" } ] }, "iosBundleId": { "anyOf": [ { "type": "string", "maxLength": 255, "pattern": "^[^\\u0000-\\u001f\\u007f]*$" }, { "type": "null" } ] }, "revision": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "defaultDomain", "desktopUrl", "playStoreUrl", "appStoreUrl", "scheme", "androidPackage", "iosBundleId", "revision", "createdAt", "updatedAt" ] }, "AppListEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/App" }, "maxItems": 100 }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "type": "object", "additionalProperties": false, "properties": { "requestId": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "requestId" ] } }, "required": [ "data", "pagination", "meta" ] }, "AppCreate": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^(?=.*\\S)[^\\u0000-\\u001f\\u007f]+$" }, "defaultDomain": { "anyOf": [ { "$ref": "#/components/schemas/Domain" }, { "type": "null" } ] }, "desktopUrl": { "anyOf": [ { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)" }, { "type": "null" } ] }, "playStoreUrl": { "anyOf": [ { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)" }, { "type": "null" } ] }, "appStoreUrl": { "anyOf": [ { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)" }, { "type": "null" } ] }, "scheme": { "anyOf": [ { "type": "string", "maxLength": 100, "pattern": "^[a-z][a-z0-9+.-]*$", "not": { "enum": [ "http", "https", "javascript", "data", "file" ] } }, { "type": "null" } ] }, "androidPackage": { "anyOf": [ { "type": "string", "maxLength": 255, "pattern": "^[A-Za-z][A-Za-z0-9_]*(?:\\.[A-Za-z][A-Za-z0-9_]*)+$" }, { "type": "null" } ] }, "iosBundleId": { "anyOf": [ { "type": "string", "maxLength": 255, "pattern": "^[A-Za-z0-9-]+(?:\\.[A-Za-z0-9-]+)+$" }, { "type": "null" } ] } }, "required": [ "name" ] }, "AppEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/App" }, "meta": { "type": "object", "additionalProperties": false, "properties": { "requestId": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "requestId" ] } }, "required": [ "data", "meta" ] }, "AppPatch": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^(?=.*\\S)[^\\u0000-\\u001f\\u007f]+$" }, "defaultDomain": { "anyOf": [ { "$ref": "#/components/schemas/Domain" }, { "type": "null" } ] }, "desktopUrl": { "anyOf": [ { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)" }, { "type": "null" } ] }, "playStoreUrl": { "anyOf": [ { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)" }, { "type": "null" } ] }, "appStoreUrl": { "anyOf": [ { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)" }, { "type": "null" } ] }, "scheme": { "anyOf": [ { "type": "string", "maxLength": 100, "pattern": "^[a-z][a-z0-9+.-]*$", "not": { "enum": [ "http", "https", "javascript", "data", "file" ] } }, { "type": "null" } ] }, "androidPackage": { "anyOf": [ { "type": "string", "maxLength": 255, "pattern": "^[A-Za-z][A-Za-z0-9_]*(?:\\.[A-Za-z][A-Za-z0-9_]*)+$" }, { "type": "null" } ] }, "iosBundleId": { "anyOf": [ { "type": "string", "maxLength": 255, "pattern": "^[A-Za-z0-9-]+(?:\\.[A-Za-z0-9-]+)+$" }, { "type": "null" } ] } }, "required": [], "minProperties": 1 }, "AppDefaults": { "type": "object", "additionalProperties": false, "properties": { "appId": { "$ref": "#/components/schemas/AppId" }, "domain": { "anyOf": [ { "$ref": "#/components/schemas/Domain" }, { "type": "null" } ] }, "desktopUrl": { "anyOf": [ { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)" }, { "type": "null" } ] }, "playStoreUrl": { "anyOf": [ { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)" }, { "type": "null" } ] }, "appStoreUrl": { "anyOf": [ { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)" }, { "type": "null" } ] }, "revision": { "type": "string", "format": "uuid" } }, "required": [ "appId", "domain", "desktopUrl", "playStoreUrl", "appStoreUrl", "revision" ] }, "AppDefaultsEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AppDefaults" }, "meta": { "type": "object", "additionalProperties": false, "properties": { "requestId": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "requestId" ] } }, "required": [ "data", "meta" ] }, "AppDefaultsPut": { "type": "object", "additionalProperties": false, "properties": { "domain": { "anyOf": [ { "$ref": "#/components/schemas/Domain" }, { "type": "null" } ] }, "desktopUrl": { "anyOf": [ { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)" }, { "type": "null" } ] }, "playStoreUrl": { "anyOf": [ { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)" }, { "type": "null" } ] }, "appStoreUrl": { "anyOf": [ { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)" }, { "type": "null" } ] } }, "required": [ "domain", "desktopUrl", "playStoreUrl", "appStoreUrl" ] }, "Asset": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "appId": { "$ref": "#/components/schemas/AppId" }, "url": { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)" }, "state": { "enum": [ "active", "deleting", "deleted" ] }, "revision": { "type": "string", "format": "uuid" }, "contentType": { "anyOf": [ { "enum": [ "image/png", "image/jpeg" ] }, { "type": "null" } ] }, "byteSize": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 1048576 }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string", "maxLength": 64, "pattern": "^[a-f0-9]{64}$" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "appId", "url", "state", "revision", "contentType", "byteSize", "sha256", "createdAt", "updatedAt" ] }, "AppLogo": { "type": "object", "additionalProperties": false, "properties": { "appId": { "$ref": "#/components/schemas/AppId" }, "asset": { "anyOf": [ { "$ref": "#/components/schemas/Asset" }, { "type": "null" } ] }, "revision": { "type": "string", "format": "uuid" } }, "required": [ "appId", "asset", "revision" ] }, "AppLogoEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AppLogo" }, "meta": { "type": "object", "additionalProperties": false, "properties": { "requestId": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "requestId" ] } }, "required": [ "data", "meta" ] }, "AppLogoPut": { "type": "object", "additionalProperties": false, "properties": { "assetId": { "type": "string", "format": "uuid" } }, "required": [ "assetId" ] }, "LinkDuplicate": { "type": "object", "additionalProperties": false, "properties": { "slug": { "type": "string", "maxLength": 200, "pattern": "^(?!.*~-)(?!\\.{1,2}$)[A-Za-z0-9._~-]*$", "minLength": 1 }, "prefix": { "type": "string", "maxLength": 200, "pattern": "^(?!.*~-)(?!\\.{1,2}$)[A-Za-z0-9._~-]*$" }, "domain": { "$ref": "#/components/schemas/Domain" }, "title": { "anyOf": [ { "type": "string", "maxLength": 1000, "pattern": "^[^\\u0000-\\u001f\\u007f]*$" }, { "type": "null" } ] } }, "required": [ "slug" ] }, "LinkValidation": { "type": "object", "additionalProperties": false, "properties": { "valid": { "const": true }, "available": { "type": "boolean" }, "normalized": { "$ref": "#/components/schemas/LinkCreate" } }, "required": [ "valid", "available", "normalized" ] }, "LinkValidationEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LinkValidation" }, "meta": { "type": "object", "additionalProperties": false, "properties": { "requestId": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "requestId" ] } }, "required": [ "data", "meta" ] }, "LinkAvailability": { "type": "object", "additionalProperties": false, "properties": { "appId": { "$ref": "#/components/schemas/AppId" }, "domain": { "$ref": "#/components/schemas/Domain" }, "prefix": { "type": "string", "maxLength": 200, "pattern": "^(?!.*~-)(?!\\.{1,2}$)[A-Za-z0-9._~-]*$" }, "slug": { "type": "string", "maxLength": 200, "pattern": "^(?!.*~-)(?!\\.{1,2}$)[A-Za-z0-9._~-]*$", "minLength": 1 }, "available": { "type": "boolean" } }, "required": [ "appId", "domain", "prefix", "slug", "available" ] }, "LinkAvailabilityEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LinkAvailability" }, "meta": { "type": "object", "additionalProperties": false, "properties": { "requestId": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "requestId" ] } }, "required": [ "data", "meta" ] }, "LinkPreview": { "type": "object", "additionalProperties": false, "properties": { "at": { "$ref": "#/components/schemas/AnalyticsInstant" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$" }, "platform": { "enum": [ "desktop", "android", "ios" ] }, "source": { "enum": [ "browser", "social" ] } }, "required": [ "platform" ] }, "LinkPreviewResult": { "type": "object", "additionalProperties": false, "properties": { "state": { "enum": [ "active", "paused", "scheduled", "expired" ] }, "allowed": { "type": "boolean" }, "matchedRuleId": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ] }, "evaluatedAt": { "type": "string", "format": "date-time" }, "linkId": { "$ref": "#/components/schemas/LinkId" }, "appId": { "$ref": "#/components/schemas/AppId" }, "platform": { "enum": [ "desktop", "android", "ios" ] }, "mode": { "enum": [ "web", "android", "ios", "recovery" ] }, "nativeUrl": { "anyOf": [ { "type": "string", "maxLength": 8192, "format": "uri" }, { "type": "null" } ] }, "fallbackUrl": { "anyOf": [ { "type": "string", "maxLength": 16384, "format": "uri", "pattern": "^https://" }, { "type": "null" } ] }, "opening": { "enum": [ "manual", "automatic" ] }, "publication": { "type": "object", "additionalProperties": false, "properties": { "status": { "enum": [ "pending", "synced", "failed" ] }, "desiredRevision": { "type": "string", "format": "uuid" }, "confirmedRevision": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "status", "desiredRevision", "confirmedRevision", "updatedAt" ] }, "sideEffects": { "const": false } }, "required": [ "state", "allowed", "matchedRuleId", "evaluatedAt", "linkId", "appId", "platform", "mode", "nativeUrl", "fallbackUrl", "opening", "publication", "sideEffects" ] }, "LinkPreviewResultEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LinkPreviewResult" }, "meta": { "type": "object", "additionalProperties": false, "properties": { "requestId": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "requestId" ] } }, "required": [ "data", "meta" ] }, "LinkPublication": { "type": "object", "additionalProperties": false, "properties": { "linkId": { "$ref": "#/components/schemas/LinkId" }, "appId": { "$ref": "#/components/schemas/AppId" }, "revision": { "type": "string", "format": "uuid" }, "status": { "enum": [ "pending", "synced", "failed" ] }, "desiredRevision": { "type": "string", "format": "uuid" }, "confirmedRevision": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "linkId", "appId", "revision", "status", "desiredRevision", "confirmedRevision", "updatedAt" ] }, "LinkPublicationEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LinkPublication" }, "meta": { "type": "object", "additionalProperties": false, "properties": { "requestId": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "requestId" ] } }, "required": [ "data", "meta" ] }, "AssetStateFilter": { "enum": [ "active", "deleting" ] }, "AssetListEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" }, "maxItems": 100 }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "type": "object", "additionalProperties": false, "properties": { "requestId": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "requestId" ] } }, "required": [ "data", "pagination", "meta" ] }, "AssetUploadForm": { "type": "object", "additionalProperties": false, "properties": { "appId": { "$ref": "#/components/schemas/AppId" }, "file": { "type": "string", "contentMediaType": "application/octet-stream" } }, "required": [ "appId", "file" ] }, "AssetEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Asset" }, "meta": { "type": "object", "additionalProperties": false, "properties": { "requestId": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "requestId" ] } }, "required": [ "data", "meta" ] }, "DateTime": { "type": "string", "format": "date-time" }, "Publication": { "type": "object", "additionalProperties": false, "properties": { "status": { "enum": [ "pending", "synced", "failed" ] }, "desiredRevision": { "$ref": "#/components/schemas/Revision" }, "confirmedRevision": { "anyOf": [ { "$ref": "#/components/schemas/Revision" }, { "type": "null" } ] }, "updatedAt": { "$ref": "#/components/schemas/DateTime" } }, "required": [ "status", "desiredRevision", "confirmedRevision", "updatedAt" ] }, "DomainResource": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "maxLength": 500 }, "appId": { "$ref": "#/components/schemas/AppId" }, "hostname": { "$ref": "#/components/schemas/Domain" }, "mode": { "enum": [ "platform", "managed", "external", "legacy" ] }, "ownership": { "type": "string", "maxLength": 30 }, "dns": { "type": "string", "maxLength": 30 }, "https": { "type": "string", "maxLength": 30 }, "links": { "type": "string", "maxLength": 30 }, "detached": { "type": "boolean" }, "removalState": { "anyOf": [ { "type": "string", "maxLength": 30 }, { "type": "null" } ] }, "canManageDns": { "type": "boolean" }, "zoneName": { "type": "string", "maxLength": 253 }, "nameservers": { "type": "array", "items": { "type": "string", "maxLength": 253 }, "maxItems": 100 }, "challenge": { "anyOf": [ { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "null" } ] }, "connectionRecords": { "type": "array", "items": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } }, "maxItems": 100 }, "nativeConfig": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } }, "revision": { "$ref": "#/components/schemas/Revision" }, "createdAt": { "$ref": "#/components/schemas/DateTime" }, "updatedAt": { "$ref": "#/components/schemas/DateTime" }, "publication": { "$ref": "#/components/schemas/Publication" }, "lastCheckedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "lastError": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] } }, "required": [ "id", "appId", "hostname", "mode", "ownership", "dns", "https", "links", "detached", "canManageDns", "revision", "createdAt", "updatedAt", "publication" ] }, "Meta": { "type": "object", "additionalProperties": false, "properties": { "requestId": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "requestId" ] }, "DomainListEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DomainResource" }, "maxItems": 100 }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "pagination", "meta" ] }, "DomainCreate": { "type": "object", "additionalProperties": false, "properties": { "appId": { "$ref": "#/components/schemas/AppId" }, "mode": { "enum": [ "platform", "managed", "external" ] }, "prefix": { "type": "string", "maxLength": 32 }, "hostname": { "$ref": "#/components/schemas/Domain" }, "apexProfileId": { "type": "string", "maxLength": 100 } }, "required": [ "appId", "mode" ] }, "DomainEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DomainResource" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "DomainCapabilities": { "type": "object", "additionalProperties": false, "properties": { "domainId": { "type": "string", "maxLength": 500 }, "appId": { "$ref": "#/components/schemas/AppId" }, "revision": { "$ref": "#/components/schemas/Revision" }, "mode": { "type": "string", "maxLength": 30 }, "actions": { "type": "object", "additionalProperties": false, "properties": { "verify": { "type": "boolean" }, "detach": { "type": "boolean" }, "dns": { "type": "boolean" }, "nativeConfig": { "type": "boolean" }, "webConfig": { "type": "boolean" }, "recovery": { "type": "boolean" }, "templates": { "type": "boolean" } }, "required": [] }, "reasons": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 2000 } } }, "required": [ "domainId", "appId", "revision", "mode", "actions", "reasons" ] }, "DomainCapabilitiesEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DomainCapabilities" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "DomainConfig": { "type": "object", "additionalProperties": false, "properties": { "domainId": { "type": "string", "maxLength": 500 }, "appId": { "$ref": "#/components/schemas/AppId" }, "revision": { "$ref": "#/components/schemas/Revision" }, "config": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } }, "publication": { "$ref": "#/components/schemas/Publication" } }, "required": [ "domainId", "appId", "revision", "config", "publication" ] }, "DomainConfigEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DomainConfig" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "NativeConfigPut": { "type": "object", "additionalProperties": false, "properties": { "androidPackage": { "type": "string", "maxLength": 255 }, "fingerprints": { "type": "array", "items": { "type": "string", "pattern": "^(?:[A-Fa-f0-9]{2}:){31}[A-Fa-f0-9]{2}$" }, "maxItems": 10 }, "ios": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "appIdPrefix": { "type": "string", "pattern": "^[A-Z0-9]{10}$" }, "bundleId": { "type": "string", "maxLength": 255 } }, "required": [ "appIdPrefix", "bundleId" ] }, { "type": "null" } ] }, "routing": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "prefixes": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 20 }, "schemeLinkFormat": { "enum": [ "app-path", "agilink-v1" ] } }, "required": [ "prefixes", "schemeLinkFormat" ] }, { "type": "null" } ] } }, "required": [] }, "WebConfigPut": { "type": "object", "additionalProperties": false, "properties": { "flutterUrl": { "type": "string", "maxLength": 4096 }, "flutterName": { "type": "string", "maxLength": 100 }, "flutterDescription": { "type": "string", "maxLength": 300 }, "flutterRoutePrefix": { "type": "string", "maxLength": 200 } }, "required": [] }, "RecoveryConfigPut": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean" }, "sdkReady": { "type": "boolean" }, "appClipBundleId": { "type": "string", "maxLength": 255 }, "detection": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean" }, "mode": { "enum": [ "confirm", "automatic" ] } }, "required": [ "enabled", "mode" ] } }, "required": [ "enabled", "sdkReady" ] }, "DomainDiagnostics": { "type": "object", "additionalProperties": false, "properties": { "domainId": { "type": "string", "maxLength": 500 }, "appId": { "$ref": "#/components/schemas/AppId" }, "revision": { "$ref": "#/components/schemas/Revision" }, "configurationSaved": { "type": "boolean" }, "publication": { "$ref": "#/components/schemas/Publication" }, "ownership": { "type": "string", "maxLength": 30 }, "dns": { "type": "string", "maxLength": 30 }, "https": { "type": "string", "maxLength": 30 }, "links": { "type": "string", "maxLength": 30 }, "androidConfigured": { "type": "boolean" }, "iosConfigured": { "type": "boolean" }, "deviceAssociationTested": { "const": false }, "appClipVerified": { "const": false }, "notes": { "type": "array", "items": { "type": "string", "maxLength": 2000 }, "maxItems": 100 } }, "required": [ "domainId", "appId", "revision", "configurationSaved", "publication", "ownership", "dns", "https", "links", "androidConfigured", "iosConfigured", "deviceAssociationTested", "appClipVerified", "notes" ] }, "DomainDiagnosticsEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DomainDiagnostics" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "DomainOptions": { "type": "object", "additionalProperties": false, "properties": { "appId": { "$ref": "#/components/schemas/AppId" }, "enabled": { "type": "boolean" }, "mutationsEnabled": { "type": "boolean" }, "platformDomain": { "anyOf": [ { "type": "string", "maxLength": 253 }, { "type": "null" } ] }, "modes": { "type": "array", "items": { "enum": [ "platform", "managed", "external" ] }, "maxItems": 100 }, "externalDns": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } }, "required": [ "appId", "enabled", "mutationsEnabled", "platformDomain", "modes", "externalDns" ] }, "DomainOptionsEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DomainOptions" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "DnsRecord": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "maxLength": 500 }, "name": { "type": "string", "maxLength": 253 }, "type": { "type": "string", "maxLength": 20 }, "content": { "type": "string", "maxLength": 4096 }, "ttl": { "type": "integer" }, "proxied": { "type": "boolean" }, "priority": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "version": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "revision": { "$ref": "#/components/schemas/Revision" }, "canEdit": { "type": "boolean" }, "canDelete": { "type": "boolean" }, "protectedReason": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] } }, "required": [ "id", "name", "type", "content", "ttl", "proxied", "priority", "version", "revision", "canEdit", "canDelete", "protectedReason" ] }, "DnsRecordListEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DnsRecord" }, "maxItems": 100 }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "pagination", "meta" ] }, "DnsRecordInput": { "type": "object", "additionalProperties": false, "properties": { "type": { "enum": [ "A", "AAAA", "CNAME", "TXT", "MX" ] }, "name": { "type": "string", "maxLength": 253 }, "content": { "type": "string", "maxLength": 2048 }, "ttl": { "type": "integer", "minimum": 1, "maximum": 86400 }, "proxied": { "type": "boolean" }, "priority": { "type": "integer", "minimum": 0, "maximum": 65535 } }, "required": [ "type", "name", "content", "ttl" ] }, "TemplateBindingView": { "type": "object", "additionalProperties": false, "properties": { "appId": { "$ref": "#/components/schemas/AppId" }, "scope": { "enum": [ "app", "domain", "link" ] }, "domainId": { "type": "string", "maxLength": 500 }, "linkId": { "$ref": "#/components/schemas/LinkId" }, "revision": { "$ref": "#/components/schemas/Revision" }, "enabled": { "type": "boolean" }, "current": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } }, "effective": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } }, "inherited": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } }, "templateData": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } }, "required": [ "appId", "scope", "revision", "enabled", "current", "effective", "inherited", "templateData" ] }, "TemplateBindingViewEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/TemplateBindingView" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "TemplateChoice": { "type": "object", "additionalProperties": false, "properties": { "mode": { "enum": [ "inherit", "official", "custom" ] }, "templateId": { "$ref": "#/components/schemas/Revision" }, "version": { "type": "integer", "minimum": 1 } }, "required": [ "mode" ] }, "TemplateBindingPut": { "type": "object", "additionalProperties": false, "properties": { "baseTemplateId": { "enum": [ "android", "ios", "recovery" ] }, "choice": { "$ref": "#/components/schemas/TemplateChoice" } }, "required": [ "baseTemplateId", "choice" ] }, "TemplateCatalogItem": { "type": "object", "additionalProperties": false, "properties": { "id": { "enum": [ "android", "ios", "recovery" ] }, "rendererContractVersion": { "const": 1 }, "states": { "type": "array", "items": { "type": "string", "maxLength": 50 }, "maxItems": 100 }, "actions": { "type": "array", "items": { "type": "string", "maxLength": 50 }, "maxItems": 100 }, "nativeVariables": { "type": "array", "items": { "type": "string", "maxLength": 100 }, "maxItems": 100 }, "themes": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } }, "required": [ "id", "rendererContractVersion", "states", "actions", "nativeVariables", "themes" ] }, "TemplateCatalogListEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateCatalogItem" }, "maxItems": 100 }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "pagination", "meta" ] }, "TemplateConfig": { "type": "object", "additionalProperties": false, "properties": { "schemaVersion": { "const": 1 }, "kind": { "const": "preset" }, "baseTemplateId": { "enum": [ "android", "ios", "recovery" ] }, "rendererContractVersion": { "const": 1 }, "appearance": { "type": "object", "additionalProperties": false, "properties": { "light": { "type": "object", "additionalProperties": false, "properties": { "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "surface": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "border": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "text": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "muted": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "accent": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "secondary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "tertiary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" } }, "required": [] }, "dark": { "type": "object", "additionalProperties": false, "properties": { "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "surface": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "border": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "text": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "muted": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "accent": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "secondary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "tertiary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" } }, "required": [] }, "fontFamily": { "enum": [ "system", "sans", "serif" ] }, "radius": { "enum": [ "small", "medium", "large" ] }, "spacing": { "enum": [ "compact", "comfortable" ] }, "logoAssetId": { "type": "string", "maxLength": 100 } }, "required": [] }, "content": { "type": "object", "additionalProperties": false, "properties": { "heading": { "type": "string", "maxLength": 120 }, "supportingText": { "type": "string", "maxLength": 1000 }, "actionLabels": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 120 } }, "details": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "label": { "type": "string", "maxLength": 80 }, "value": { "type": "string", "maxLength": 1000 } }, "required": [ "label", "value" ] }, "maxItems": 4 } }, "required": [] }, "variables": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" }, "label": { "type": "string", "maxLength": 80 }, "type": { "enum": [ "text", "number", "boolean" ] }, "required": { "type": "boolean" }, "maxLength": { "type": "integer", "minimum": 1, "maximum": 4000 }, "defaultValue": { "type": [ "string", "number", "boolean" ] } }, "required": [ "key" ] }, "maxItems": 20 } }, "required": [] }, "TemplateSchemaResult": { "type": "object", "additionalProperties": false, "properties": { "baseTemplateId": { "enum": [ "android", "ios", "recovery" ] }, "limits": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } }, "schema": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } }, "example": { "$ref": "#/components/schemas/TemplateConfig" } }, "required": [ "baseTemplateId", "limits", "schema", "example" ] }, "TemplateSchemaResultEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/TemplateSchemaResult" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "TemplateChoiceItem": { "type": "object", "additionalProperties": false, "properties": { "templateId": { "$ref": "#/components/schemas/Revision" }, "version": { "type": "integer", "minimum": 1 }, "baseTemplateId": { "enum": [ "android", "ios", "recovery" ] }, "name": { "type": "string", "maxLength": 100 }, "variables": { "type": "array", "items": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } }, "maxItems": 20 } }, "required": [ "templateId", "version", "baseTemplateId", "name", "variables" ] }, "TemplateChoiceListEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateChoiceItem" }, "maxItems": 100 }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "pagination", "meta" ] }, "TemplateMeta": { "type": "object", "additionalProperties": false, "properties": { "id": { "$ref": "#/components/schemas/Revision" }, "appId": { "$ref": "#/components/schemas/AppId" }, "name": { "type": "string", "maxLength": 100 }, "baseTemplateId": { "enum": [ "android", "ios", "recovery" ] }, "archived": { "type": "boolean" }, "revision": { "$ref": "#/components/schemas/Revision" }, "createdAt": { "$ref": "#/components/schemas/DateTime" }, "updatedAt": { "$ref": "#/components/schemas/DateTime" } }, "required": [ "id", "appId", "name", "baseTemplateId", "archived", "revision", "createdAt", "updatedAt" ] }, "TemplateListEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateMeta" }, "maxItems": 100 }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "pagination", "meta" ] }, "TemplateCreate": { "type": "object", "additionalProperties": false, "properties": { "appId": { "$ref": "#/components/schemas/AppId" }, "name": { "type": "string", "maxLength": 100 }, "baseTemplateId": { "enum": [ "android", "ios", "recovery" ] }, "config": { "$ref": "#/components/schemas/TemplateConfig" } }, "required": [ "appId", "name", "baseTemplateId" ] }, "TemplateDraft": { "type": "object", "additionalProperties": false, "properties": { "templateId": { "$ref": "#/components/schemas/Revision" }, "config": { "$ref": "#/components/schemas/TemplateConfig" }, "revision": { "$ref": "#/components/schemas/Revision" }, "baseVersion": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "updatedAt": { "$ref": "#/components/schemas/DateTime" } }, "required": [ "templateId", "config", "revision", "baseVersion", "updatedAt" ] }, "TemplateDetail": { "type": "object", "additionalProperties": false, "properties": { "template": { "$ref": "#/components/schemas/TemplateMeta" }, "draft": { "$ref": "#/components/schemas/TemplateDraft" }, "revision": { "$ref": "#/components/schemas/Revision" } }, "required": [ "template", "draft", "revision" ] }, "TemplateDetailEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/TemplateDetail" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "TemplatePatch": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 100 }, "archived": { "type": "boolean" } }, "required": [] }, "TemplateDuplicate": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 100 }, "sourceVersion": { "type": "integer", "minimum": 1 }, "draftRevision": { "$ref": "#/components/schemas/Revision" } }, "required": [ "name" ] }, "TemplateDraftEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/TemplateDraft" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "TemplateDraftPut": { "type": "object", "additionalProperties": false, "properties": { "config": { "$ref": "#/components/schemas/TemplateConfig" } }, "required": [ "config" ] }, "TemplateValidate": { "type": "object", "additionalProperties": false, "properties": { "config": { "$ref": "#/components/schemas/TemplateConfig" }, "usage": { "enum": [ "link", "default" ] } }, "required": [ "config" ] }, "TemplateValidationResult": { "type": "object", "additionalProperties": false, "properties": { "valid": { "const": true }, "config": { "$ref": "#/components/schemas/TemplateConfig" }, "usage": { "enum": [ "link", "default" ] } }, "required": [ "valid", "config", "usage" ] }, "TemplateValidationResultEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/TemplateValidationResult" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "TemplatePreview": { "type": "object", "additionalProperties": false, "properties": { "config": { "$ref": "#/components/schemas/TemplateConfig" }, "linkId": { "$ref": "#/components/schemas/LinkId" }, "templateData": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } }, "required": [] }, "TemplatePreviewResult": { "type": "object", "additionalProperties": false, "properties": { "templateId": { "$ref": "#/components/schemas/Revision" }, "config": { "$ref": "#/components/schemas/TemplateConfig" }, "content": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } }, "sideEffects": { "const": false }, "rendererContractVersion": { "const": 1 } }, "required": [ "templateId", "config", "content", "sideEffects", "rendererContractVersion" ] }, "TemplatePreviewResultEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/TemplatePreviewResult" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "TemplateVersion": { "type": "object", "additionalProperties": false, "properties": { "templateId": { "$ref": "#/components/schemas/Revision" }, "version": { "type": "integer", "minimum": 1 }, "state": { "const": "prepared" }, "config": { "$ref": "#/components/schemas/TemplateConfig" }, "checksum": { "type": "string", "maxLength": 64 }, "usage": { "enum": [ "link", "default" ] }, "authorId": { "$ref": "#/components/schemas/Revision" }, "createdAt": { "$ref": "#/components/schemas/DateTime" } }, "required": [ "templateId", "version", "state", "config", "checksum", "usage", "authorId", "createdAt" ] }, "TemplateVersionListEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateVersion" }, "maxItems": 100 }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "pagination", "meta" ] }, "TemplateVersionCreate": { "type": "object", "additionalProperties": false, "properties": { "draftRevision": { "$ref": "#/components/schemas/Revision" }, "usage": { "enum": [ "link", "default" ] } }, "required": [ "draftRevision" ] }, "TemplateSnapshot": { "type": "object", "additionalProperties": false, "properties": { "template": { "$ref": "#/components/schemas/TemplateMeta" }, "version": { "$ref": "#/components/schemas/TemplateVersion" }, "draft": { "type": "object", "additionalProperties": false, "properties": { "revision": { "$ref": "#/components/schemas/Revision" }, "baseVersion": { "type": "integer" }, "updatedAt": { "$ref": "#/components/schemas/DateTime" } }, "required": [ "revision", "baseVersion", "updatedAt" ] }, "revision": { "$ref": "#/components/schemas/Revision" } }, "required": [ "template", "version", "draft", "revision" ] }, "TemplateSnapshotEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/TemplateSnapshot" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "TemplateVersionEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/TemplateVersion" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "TemplateAvailabilityItem": { "type": "object", "additionalProperties": false, "properties": { "version": { "type": "integer", "minimum": 1 }, "confirmedAt": { "$ref": "#/components/schemas/DateTime" } }, "required": [ "version", "confirmedAt" ] }, "TemplateAvailabilityListEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateAvailabilityItem" }, "maxItems": 100 }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "pagination", "meta" ] }, "TemplateTarget": { "type": "object", "additionalProperties": false, "properties": { "scope": { "enum": [ "app", "domain", "link" ] }, "domainId": { "type": "string", "maxLength": 500 }, "linkId": { "$ref": "#/components/schemas/LinkId" }, "expectedRevision": { "anyOf": [ { "$ref": "#/components/schemas/Revision" }, { "type": "null" } ] }, "expectedLinkRevision": { "$ref": "#/components/schemas/Revision" } }, "required": [ "scope", "expectedRevision" ] }, "TemplatePublish": { "type": "object", "additionalProperties": false, "properties": { "version": { "type": "integer", "minimum": 1 }, "draftRevision": { "$ref": "#/components/schemas/Revision" }, "usage": { "enum": [ "link", "default" ] }, "targets": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateTarget" }, "maxItems": 50 } }, "required": [ "targets" ] }, "TemplatePublication": { "type": "object", "additionalProperties": false, "properties": { "id": { "$ref": "#/components/schemas/Revision" }, "appId": { "$ref": "#/components/schemas/AppId" }, "revision": { "$ref": "#/components/schemas/Revision" }, "action": { "enum": [ "publish", "restore" ] }, "baseTemplateId": { "enum": [ "android", "ios", "recovery" ] }, "choice": { "$ref": "#/components/schemas/TemplateChoice" }, "state": { "enum": [ "queued", "applying", "confirmed", "partial", "conflict", "superseded", "denied" ] }, "phase": { "enum": [ "version", "activation", "projection" ] }, "error": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "versionAvailability": { "anyOf": [ { "enum": [ "available", "prepared" ] }, { "type": "null" } ] }, "createdAt": { "$ref": "#/components/schemas/DateTime" }, "updatedAt": { "$ref": "#/components/schemas/DateTime" }, "targets": { "type": "array", "items": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } }, "maxItems": 50 } }, "required": [ "id", "appId", "revision", "action", "baseTemplateId", "choice", "state", "phase", "error", "versionAvailability", "createdAt", "updatedAt", "targets" ] }, "TemplatePublicationEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/TemplatePublication" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "TemplateRestore": { "type": "object", "additionalProperties": false, "properties": { "version": { "type": "integer", "minimum": 1 }, "mode": { "enum": [ "official", "inherit" ] }, "targets": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateTarget" }, "maxItems": 50 } }, "required": [ "targets" ] }, "BaseId": { "enum": [ "android", "ios", "recovery" ] }, "TemplatePublicationListEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TemplatePublication" }, "maxItems": 100 }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "pagination", "meta" ] }, "AnalyticsPeriod": { "type": "object", "additionalProperties": false, "properties": { "start": { "$ref": "#/components/schemas/AnalyticsInstant" }, "end": { "$ref": "#/components/schemas/AnalyticsInstant" }, "timezone": { "type": "string", "maxLength": 100 }, "startInclusive": { "const": true }, "endExclusive": { "const": true } }, "required": [ "start", "end", "timezone", "startInclusive", "endExclusive" ] }, "AnalyticsFilters": { "type": "object", "additionalProperties": false, "properties": { "campaignId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "folderId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "tagId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "group": { "enum": [ "all", "main", "operational" ] }, "linkId": { "anyOf": [ { "$ref": "#/components/schemas/LinkId" }, { "type": "null" } ] }, "domain": { "anyOf": [ { "$ref": "#/components/schemas/Domain" }, { "type": "null" } ] }, "prefix": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "device": { "anyOf": [ { "enum": [ "android", "ios", "desktop", "unknown" ] }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string", "maxLength": 7 }, { "type": "null" } ] }, "eventType": { "enum": [ "all", "click", "app_open", "content_view", "legacy_content_load" ] } }, "required": [ "campaignId", "folderId", "tagId", "group", "linkId", "domain", "prefix", "device", "source", "country", "eventType" ] }, "AnalyticsCoverage": { "type": "object", "additionalProperties": false, "properties": { "source": { "enum": [ "event_rows", "retained_recovery_tokens" ] }, "grouping": { "const": "current_link_group" }, "deletedLinks": { "const": "excluded" }, "historicalAggregates": { "const": "not_merged" }, "uniqueVisitors": { "const": "distinct_click_hash_estimate" }, "nativeTrust": { "const": "client_reported" }, "completenessGuaranteed": { "const": false }, "limitations": { "type": "array", "items": { "type": "string", "maxLength": 1000 }, "maxItems": 1000 } }, "required": [ "source", "grouping", "deletedLinks", "historicalAggregates", "uniqueVisitors", "nativeTrust", "completenessGuaranteed", "limitations" ] }, "AnalyticsSummary": { "type": "object", "additionalProperties": false, "properties": { "appId": { "$ref": "#/components/schemas/AppId" }, "period": { "$ref": "#/components/schemas/AnalyticsPeriod" }, "filters": { "$ref": "#/components/schemas/AnalyticsFilters" }, "generatedAt": { "type": "string", "format": "date-time" }, "coverage": { "$ref": "#/components/schemas/AnalyticsCoverage" }, "totals": { "type": "object", "additionalProperties": false, "properties": { "clicks": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "uniqueVisitors": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "identifiedClicks": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "appOpens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "contentViews": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "legacyContentLoads": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "activeLinks": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "firstEventAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastEventAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "clicks", "uniqueVisitors", "identifiedClicks", "appOpens", "contentViews", "legacyContentLoads", "activeLinks", "firstEventAt", "lastEventAt" ] } }, "required": [ "appId", "period", "filters", "generatedAt", "coverage", "totals" ] }, "AnalyticsSummaryEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AnalyticsSummary" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "AnalyticsTimeseries": { "type": "object", "additionalProperties": false, "properties": { "appId": { "$ref": "#/components/schemas/AppId" }, "period": { "$ref": "#/components/schemas/AnalyticsPeriod" }, "filters": { "$ref": "#/components/schemas/AnalyticsFilters" }, "generatedAt": { "type": "string", "format": "date-time" }, "coverage": { "$ref": "#/components/schemas/AnalyticsCoverage" }, "granularity": { "enum": [ "hour", "day", "month", "year" ] }, "sparse": { "const": true }, "buckets": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "start": { "type": "string", "format": "date-time" }, "localLabel": { "type": "string", "maxLength": 40 }, "clicks": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "uniqueVisitors": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "identifiedClicks": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "appOpens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "contentViews": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "legacyContentLoads": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "start", "localLabel", "clicks", "uniqueVisitors", "identifiedClicks", "appOpens", "contentViews", "legacyContentLoads" ] }, "maxItems": 1000 } }, "required": [ "appId", "period", "filters", "generatedAt", "coverage", "granularity", "sparse", "buckets" ] }, "AnalyticsTimeseriesEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AnalyticsTimeseries" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "AnalyticsBreakdown": { "type": "object", "additionalProperties": false, "properties": { "appId": { "$ref": "#/components/schemas/AppId" }, "period": { "$ref": "#/components/schemas/AnalyticsPeriod" }, "filters": { "$ref": "#/components/schemas/AnalyticsFilters" }, "generatedAt": { "type": "string", "format": "date-time" }, "coverage": { "$ref": "#/components/schemas/AnalyticsCoverage" }, "dimension": { "enum": [ "device", "source", "country", "eventType", "producer", "entryMethod" ] }, "truncated": { "type": "boolean" }, "items": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "value": { "type": "string", "maxLength": 200 }, "events": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "clicks": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "uniqueVisitors": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "identifiedClicks": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "appOpens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "contentViews": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "legacyContentLoads": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "value", "events", "clicks", "uniqueVisitors", "identifiedClicks", "appOpens", "contentViews", "legacyContentLoads" ] }, "maxItems": 1000 } }, "required": [ "appId", "period", "filters", "generatedAt", "coverage", "dimension", "truncated", "items" ] }, "AnalyticsBreakdownEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AnalyticsBreakdown" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "AnalyticsTopLinks": { "type": "object", "additionalProperties": false, "properties": { "appId": { "$ref": "#/components/schemas/AppId" }, "period": { "$ref": "#/components/schemas/AnalyticsPeriod" }, "filters": { "$ref": "#/components/schemas/AnalyticsFilters" }, "generatedAt": { "type": "string", "format": "date-time" }, "coverage": { "$ref": "#/components/schemas/AnalyticsCoverage" }, "items": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "linkId": { "$ref": "#/components/schemas/LinkId" }, "title": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "domain": { "$ref": "#/components/schemas/Domain" }, "prefix": { "type": "string", "maxLength": 200 }, "slug": { "type": "string", "maxLength": 200 }, "clicks": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "uniqueVisitors": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lastClickAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "linkId", "title", "domain", "prefix", "slug", "clicks", "uniqueVisitors", "lastClickAt" ] }, "maxItems": 1000 } }, "required": [ "appId", "period", "filters", "generatedAt", "coverage", "items" ] }, "AnalyticsTopLinksEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AnalyticsTopLinks" }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "pagination", "meta" ] }, "AnalyticsEvent": { "type": "object", "additionalProperties": false, "properties": { "id": { "$ref": "#/components/schemas/OpaqueId" }, "appId": { "$ref": "#/components/schemas/AppId" }, "linkId": { "$ref": "#/components/schemas/LinkId" }, "type": { "enum": [ "click", "app_open", "content_view", "legacy_content_load" ] }, "producer": { "enum": [ "legacy_unknown", "worker", "flutter_sdk", "pilot_legacy" ] }, "trust": { "enum": [ "worker_observed", "client_reported", "legacy_unknown" ] }, "occurredAt": { "type": "string", "format": "date-time" }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "device": { "type": "string", "maxLength": 7 }, "source": { "type": "string", "maxLength": 200 }, "country": { "type": "string", "maxLength": 7 }, "entryMethod": { "type": "string", "maxLength": 200 }, "openId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "parentEventId": { "anyOf": [ { "$ref": "#/components/schemas/OpaqueId" }, { "type": "null" } ] } }, "required": [ "id", "appId", "linkId", "type", "producer", "trust", "occurredAt", "receivedAt", "device", "source", "country", "entryMethod", "openId", "parentEventId" ] }, "AnalyticsEvents": { "type": "object", "additionalProperties": false, "properties": { "appId": { "$ref": "#/components/schemas/AppId" }, "period": { "$ref": "#/components/schemas/AnalyticsPeriod" }, "filters": { "$ref": "#/components/schemas/AnalyticsFilters" }, "generatedAt": { "type": "string", "format": "date-time" }, "coverage": { "$ref": "#/components/schemas/AnalyticsCoverage" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyticsEvent" }, "maxItems": 1000 } }, "required": [ "appId", "period", "filters", "generatedAt", "coverage", "events" ] }, "AnalyticsEventsEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AnalyticsEvents" }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "pagination", "meta" ] }, "AnalyticsNative": { "type": "object", "additionalProperties": false, "properties": { "appId": { "$ref": "#/components/schemas/AppId" }, "period": { "$ref": "#/components/schemas/AnalyticsPeriod" }, "filters": { "$ref": "#/components/schemas/AnalyticsFilters" }, "generatedAt": { "type": "string", "format": "date-time" }, "coverage": { "$ref": "#/components/schemas/AnalyticsCoverage" }, "appOpens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "contentViews": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "legacyContentLoads": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "confirmedOpens24h": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "matureOpens24h": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "provisionalOpens24h": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "cohortWindowHours": { "const": 24 }, "contentViewRate24h": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] } }, "required": [ "appId", "period", "filters", "generatedAt", "coverage", "appOpens", "contentViews", "legacyContentLoads", "confirmedOpens24h", "matureOpens24h", "provisionalOpens24h", "cohortWindowHours", "contentViewRate24h" ] }, "AnalyticsNativeEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AnalyticsNative" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "AnalyticsRecovery": { "type": "object", "additionalProperties": false, "properties": { "appId": { "$ref": "#/components/schemas/AppId" }, "period": { "$ref": "#/components/schemas/AnalyticsPeriod" }, "filters": { "$ref": "#/components/schemas/AnalyticsFilters" }, "generatedAt": { "type": "string", "format": "date-time" }, "coverage": { "$ref": "#/components/schemas/AnalyticsCoverage" }, "issuedTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "stages": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "stage": { "enum": [ "page_presented", "copied", "store_choice", "clip_preview", "recovered" ] }, "eventCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "stage", "eventCount", "tokens" ] }, "maxItems": 1000 } }, "required": [ "appId", "period", "filters", "generatedAt", "coverage", "issuedTokens", "stages" ] }, "AnalyticsRecoveryEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AnalyticsRecovery" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "LinkHistoryEvent": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "linkId": { "$ref": "#/components/schemas/LinkId" }, "appId": { "$ref": "#/components/schemas/AppId" }, "action": { "enum": [ "create", "update", "delete" ] }, "fields": { "type": "array", "items": { "type": "string", "maxLength": 100 }, "maxItems": 100 }, "revision": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "linkId", "appId", "action", "fields", "revision", "createdAt" ] }, "LinkHistoryListEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LinkHistoryEvent" }, "maxItems": 100 }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "pagination", "meta" ] }, "LinkTags": { "type": "object", "additionalProperties": false, "properties": { "linkId": { "$ref": "#/components/schemas/LinkId" }, "appId": { "$ref": "#/components/schemas/AppId" }, "revision": { "type": "string", "format": "uuid" }, "tagIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 20, "uniqueItems": true } }, "required": [ "linkId", "appId", "revision", "tagIds" ] }, "LinkTagsEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LinkTags" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "LinkTagsPut": { "type": "object", "additionalProperties": false, "properties": { "tagIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 20, "uniqueItems": true } }, "required": [ "tagIds" ] }, "RoutingRule": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "maxLength": 50, "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$" }, "platform": { "enum": [ "all", "desktop", "android", "ios" ] }, "country": { "anyOf": [ { "type": "string", "pattern": "^[A-Z]{2}$" }, { "type": "null" } ] }, "startsAt": { "anyOf": [ { "$ref": "#/components/schemas/AnalyticsInstant" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "$ref": "#/components/schemas/AnalyticsInstant" }, { "type": "null" } ] }, "destinationUrl": { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)" }, "utm": { "$ref": "#/components/schemas/UtmParameters" } }, "required": [ "id", "platform", "country", "startsAt", "expiresAt", "destinationUrl", "utm" ] }, "LinkRoutingRules": { "type": "object", "additionalProperties": false, "properties": { "linkId": { "$ref": "#/components/schemas/LinkId" }, "appId": { "$ref": "#/components/schemas/AppId" }, "revision": { "type": "string", "format": "uuid" }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingRule" }, "maxItems": 10 } }, "required": [ "linkId", "appId", "revision", "rules" ] }, "LinkRoutingRulesEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LinkRoutingRules" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "RoutingRulesPut": { "type": "object", "additionalProperties": false, "properties": { "rules": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingRule" }, "maxItems": 10 } }, "required": [ "rules" ] }, "SearchText": { "type": "string", "maxLength": 200, "pattern": "^[^\\u0000-\\u001f\\u007f]*$" }, "Organization": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "appId": { "$ref": "#/components/schemas/AppId" }, "kind": { "enum": [ "tags", "folders", "campaigns" ] }, "name": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^[^\\u0000-\\u001f\\u007f]+$" }, "description": { "type": "string", "maxLength": 1000, "pattern": "^[^\\u0000-\\u001f\\u007f]*$" }, "archived": { "type": "boolean" }, "utm": { "$ref": "#/components/schemas/UtmParameters" }, "revision": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "appId", "kind", "name", "description", "archived", "utm", "revision", "createdAt", "updatedAt" ] }, "OrganizationListEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Organization" }, "maxItems": 100 }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "pagination", "meta" ] }, "OrganizationCreate": { "type": "object", "additionalProperties": false, "properties": { "appId": { "$ref": "#/components/schemas/AppId" }, "name": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^[^\\u0000-\\u001f\\u007f]+$" }, "description": { "type": "string", "maxLength": 1000, "pattern": "^[^\\u0000-\\u001f\\u007f]*$" }, "archived": { "type": "boolean" }, "utm": { "$ref": "#/components/schemas/UtmParameters" } }, "required": [ "appId", "name" ] }, "OrganizationEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Organization" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "OrganizationPatch": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^[^\\u0000-\\u001f\\u007f]+$" }, "description": { "type": "string", "maxLength": 1000, "pattern": "^[^\\u0000-\\u001f\\u007f]*$" }, "archived": { "type": "boolean" }, "utm": { "$ref": "#/components/schemas/UtmParameters" } }, "required": [], "minProperties": 1 }, "QrStyle": { "type": "object", "additionalProperties": false, "properties": { "size": { "type": "integer", "minimum": 256, "maximum": 1024 }, "margin": { "type": "integer", "minimum": 4, "maximum": 16 }, "errorCorrectionLevel": { "enum": [ "M", "Q", "H" ] }, "dark": { "enum": [ "#000000", "#0f172a" ] }, "light": { "const": "#ffffff" } }, "required": [ "size", "margin", "errorCorrectionLevel", "dark", "light" ] }, "QrCode": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "appId": { "$ref": "#/components/schemas/AppId" }, "linkId": { "$ref": "#/components/schemas/LinkId" }, "url": { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)" }, "name": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^[^\\u0000-\\u001f\\u007f]+$" }, "style": { "$ref": "#/components/schemas/QrStyle" }, "revision": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "appId", "linkId", "url", "name", "style", "revision", "createdAt", "updatedAt" ] }, "QrCodeListEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/QrCode" }, "maxItems": 100 }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "pagination", "meta" ] }, "QrCreate": { "type": "object", "additionalProperties": false, "properties": { "appId": { "$ref": "#/components/schemas/AppId" }, "linkId": { "$ref": "#/components/schemas/LinkId" }, "name": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^[^\\u0000-\\u001f\\u007f]+$" }, "style": { "$ref": "#/components/schemas/QrStyle" } }, "required": [ "appId", "linkId", "name" ] }, "QrCodeEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/QrCode" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "QrPatch": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^[^\\u0000-\\u001f\\u007f]+$" }, "style": { "$ref": "#/components/schemas/QrStyle" } }, "required": [], "minProperties": 1 }, "ExportCreate": { "type": "object", "additionalProperties": false, "properties": { "appId": { "$ref": "#/components/schemas/AppId" }, "dataset": { "enum": [ "links", "events", "summary" ] }, "format": { "enum": [ "csv", "json" ] }, "filters": { "type": "object", "additionalProperties": false, "properties": { "start": { "$ref": "#/components/schemas/AnalyticsInstant" }, "end": { "$ref": "#/components/schemas/AnalyticsInstant" }, "timezone": { "const": "UTC" }, "group": { "enum": [ "all", "main", "operational" ] } }, "required": [] } }, "required": [ "appId", "dataset", "format" ] }, "AutomationTask": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "appId": { "$ref": "#/components/schemas/AppId" }, "kind": { "enum": [ "batch", "import", "export" ] }, "state": { "enum": [ "uploaded", "validated", "queued", "running", "succeeded", "partially_succeeded", "failed", "cancel_requested", "cancelled" ] }, "operationId": { "anyOf": [ { "$ref": "#/components/schemas/OpaqueId" }, { "type": "null" } ] }, "revision": { "type": "string", "format": "uuid" }, "total": { "type": "integer", "minimum": 0, "maximum": 1000 }, "succeeded": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "downloadUrl": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] } }, "required": [ "id", "appId", "kind", "state", "operationId", "revision", "total", "succeeded", "failed", "expiresAt", "createdAt", "updatedAt", "downloadUrl" ] }, "AutomationEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AutomationTask" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "BatchItem": { "type": "object", "additionalProperties": false, "properties": { "clientId": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^[A-Za-z0-9_.-]+$" }, "action": { "enum": [ "create", "update", "move", "archive", "delete" ] }, "linkId": { "$ref": "#/components/schemas/LinkId" }, "revision": { "type": "string", "format": "uuid" }, "input": { "type": "object", "maxProperties": 40, "additionalProperties": true } }, "required": [ "clientId", "action" ] }, "BatchCreate": { "type": "object", "additionalProperties": false, "properties": { "appId": { "$ref": "#/components/schemas/AppId" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/BatchItem" }, "maxItems": 50, "minItems": 1 } }, "required": [ "appId", "items" ] }, "AutomationItem": { "type": "object", "additionalProperties": false, "properties": { "clientId": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^[A-Za-z0-9_.-]+$" }, "ordinal": { "type": "integer", "minimum": 1, "maximum": 50 }, "state": { "enum": [ "pending", "valid", "invalid", "succeeded", "failed" ] }, "result": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "id": { "$ref": "#/components/schemas/LinkId" }, "revision": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] } }, "required": [ "id", "revision" ] }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string", "maxLength": 100 }, "message": { "type": "string", "maxLength": 300 } }, "required": [ "code", "message" ] }, { "type": "null" } ] } }, "required": [ "clientId", "ordinal", "state", "result", "error" ] }, "AutomationItemListEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationItem" }, "maxItems": 100 }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "pagination", "meta" ] }, "ImportCreate": { "type": "object", "additionalProperties": false, "properties": { "appId": { "$ref": "#/components/schemas/AppId" }, "format": { "enum": [ "csv", "json" ] }, "content": { "type": "string", "maxLength": 24000, "minLength": 1 }, "mapping": { "type": "object", "maxProperties": 30, "additionalProperties": { "enum": [ "clientId", "domain", "prefix", "slug", "title", "description", "desktopUrl", "playStoreUrl", "appStoreUrl", "appPath", "webOnly", "behavior", "group" ] } } }, "required": [ "appId", "format", "content" ] }, "Webhook": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "appId": { "$ref": "#/components/schemas/AppId" }, "name": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^[^\\u0000-\\u001f\\u007f]+$" }, "url": { "type": "string", "maxLength": 2048, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:/[^#]*)?$" }, "events": { "type": "array", "items": { "enum": [ "link.created", "link.updated", "link.deleted", "domain.status_changed", "template.publication_succeeded", "template.publication_failed", "operation.completed", "operation.failed", "export.ready" ] }, "maxItems": 9, "minItems": 1, "uniqueItems": true }, "enabled": { "type": "boolean" }, "failures": { "type": "integer", "minimum": 0 }, "revision": { "type": "string", "format": "uuid" }, "previousSecretExpiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "appId", "name", "url", "events", "enabled", "failures", "revision", "previousSecretExpiresAt", "createdAt", "updatedAt" ] }, "WebhookListEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" }, "maxItems": 100 }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "pagination", "meta" ] }, "WebhookCreate": { "type": "object", "additionalProperties": false, "properties": { "appId": { "$ref": "#/components/schemas/AppId" }, "name": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^[^\\u0000-\\u001f\\u007f]+$" }, "url": { "type": "string", "maxLength": 2048, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:/[^#]*)?$" }, "events": { "type": "array", "items": { "enum": [ "link.created", "link.updated", "link.deleted", "domain.status_changed", "template.publication_succeeded", "template.publication_failed", "operation.completed", "operation.failed", "export.ready" ] }, "maxItems": 9, "minItems": 1, "uniqueItems": true } }, "required": [ "appId", "name", "url", "events" ] }, "WebhookIssuedEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "object", "additionalProperties": false, "properties": { "webhook": { "$ref": "#/components/schemas/Webhook" }, "secret": { "type": "string", "pattern": "^whsec_[A-Za-z0-9_-]{43}$" } }, "required": [ "webhook", "secret" ] }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "WebhookEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Webhook" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "WebhookPatch": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^[^\\u0000-\\u001f\\u007f]+$" }, "url": { "type": "string", "maxLength": 2048, "format": "uri", "pattern": "^https://[^/@?#\\s]+(?:/[^#]*)?$" }, "events": { "type": "array", "items": { "enum": [ "link.created", "link.updated", "link.deleted", "domain.status_changed", "template.publication_succeeded", "template.publication_failed", "operation.completed", "operation.failed", "export.ready" ] }, "maxItems": 9, "minItems": 1, "uniqueItems": true }, "enabled": { "type": "boolean" } }, "required": [], "minProperties": 1 }, "WebhookRotate": { "type": "object", "additionalProperties": false, "properties": { "overlapSeconds": { "type": "integer", "minimum": 0, "maximum": 86400 } }, "required": [] }, "Delivery": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "appId": { "$ref": "#/components/schemas/AppId" }, "webhookId": { "type": "string", "format": "uuid" }, "eventId": { "type": "string", "format": "uuid" }, "eventType": { "enum": [ "link.created", "link.updated", "link.deleted", "domain.status_changed", "template.publication_succeeded", "template.publication_failed", "operation.completed", "operation.failed", "export.ready", "webhook.test" ] }, "test": { "type": "boolean" }, "state": { "enum": [ "pending", "sending", "succeeded", "failed", "cancelled" ] }, "attempts": { "type": "integer", "minimum": 0, "maximum": 5 }, "statusCode": { "anyOf": [ { "type": "integer", "minimum": 100, "maximum": 599 }, { "type": "null" } ] }, "errorCode": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "nextAttemptAt": { "type": "string", "format": "date-time" }, "revision": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "appId", "webhookId", "eventId", "eventType", "test", "state", "attempts", "statusCode", "errorCode", "nextAttemptAt", "revision", "createdAt", "expiresAt" ] }, "DeliveryEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Delivery" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "DeliveryListEnvelope": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Delivery" }, "maxItems": 100 }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "pagination", "meta" ] } } } }