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: <bytes do arquivo PNG ou JPEG>
            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
                go.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