<!-- Generated by scripts/generate-ai-docs.mjs. Do not edit by hand. -->
# Hermes Publisher API

> API operacional do Hermes Studio para inteligência editorial, criação, fluxo de aprovação, equipe e conexões sociais.

Version: 1.3.0
Release date: 2026-08-22
Base URL: https://socialmedia.janvalellam.com.br
MCP Streamable HTTP: https://socialmedia.janvalellam.com.br/api/mcp
Canonical OpenAPI: https://socialmedia.janvalellam.com.br/api/ai/openapi.yaml

## Authentication and safety

- Send `Authorization: Bearer <access token>` only to routes marked as authenticated. Normal protected routes accept an active Supabase session or an `hms_live_` personal token.
- Routes marked `session only` accept only a Supabase session. Personal tokens cannot create/reveal tokens, administer access, manage members, or start/disconnect OAuth connections.
- Supabase Studio sessions receive capabilities exclusively from the member `access_level` role. `api_access_level` never limits or disables a Studio session.
- Only personal tokens use the individual API level. They are hash-only on the server, expire in 1–90 days, reveal their secret once, and are limited by token scopes plus `api_access_level` plus the current Studio role ceiling.
- Personal-token API levels are `nenhum`, `leitor`, `criador`, `lider`, and `admin`; changing them affects PATs immediately without changing Studio-session permissions.
- The credential must belong to an active `team_members` record. Capabilities are enforced by the server and authorization activity is audited without request bodies or secrets.
- Use `api_revision`/`updated_at` as opaque CAS tokens and `Idempotency-Key` when the operation supports it.
- Never send or store provider credentials, service-role keys, `.env` contents, temporary passwords, or access tokens in prompts/logs.
- Read the exact current object before a mutation. Destructive, publishing, permission, and external actions require explicit user intent.
- MCP tools are an explicit allowlist; never use them to bypass route capabilities or validation.

## Operations

- `GET /api/access/audit` — Consultar a trilha de auditoria da API (Supabase session; capability: team_admin)
- `GET /api/access/catalog` — Consultar o catálogo de rotas e ferramentas MCP (Central da API) (Supabase session; capability: team_admin)
- `GET /api/access/me` — Consultar o próprio acesso individual à API (Supabase session)
- `GET /api/access/members` — Listar acessos individuais da equipe (Supabase session; capability: team_admin)
- `PATCH /api/access/members/{memberId}` — Alterar o nível individual de API de um membro (Supabase session; capability: team_admin)
- `DELETE /api/access/members/{memberId}/tokens/{tokenId}` — Revogar um token pessoal como administrador (Supabase session; capability: team_admin)
- `GET /api/access/tokens` — Listar os próprios tokens pessoais (Supabase session)
- `POST /api/access/tokens` — Criar um token pessoal com escopo e expiração (Supabase session)
- `DELETE /api/access/tokens/{tokenId}` — Revogar um token pessoal próprio (Supabase session)
- `GET /api/ai/SKILL.md` — Baixar a skill operacional do Hermes (public)
- `GET /api/ai/chatgpt.md` — Baixar instruções para ChatGPT (public)
- `GET /api/ai/claude.md` — Baixar instruções para Claude (public)
- `GET /api/ai/cursor.mdc` — Baixar regras do Cursor (public)
- `GET /api/ai/hermes.mjs` — Baixar a CLI Hermes (public)
- `GET /api/ai/llms-full.txt` — Baixar a referência completa para LLMs (public)
- `GET /api/ai/llms.txt` — Baixar o índice conciso para LLMs (public)
- `GET /api/ai/manifest.json` — Baixar o manifesto verificável dos artefatos (public)
- `GET /api/ai/mcp-setup.md` — Baixar instruções de conexão MCP (public)
- `GET /api/ai/openapi.json` — Baixar o contrato OpenAPI 3.1 (public)
- `GET /api/ai/openapi.yaml` — Baixar o contrato OpenAPI 3.1 em YAML (public)
- `GET /api/ai/postman.json` — Baixar a coleção Postman gerada (public)
- `GET /api/ai/skill.zip` — Baixar a skill completa e instalável (public)
- `GET /api/anexaveis` — Listar eventos que aceitam mídia do membro (session or personal token; capability: art)
- `GET /api/aprovacoes` — Listar conteúdos aguardando aprovação (session or personal token; capability: approve)
- `POST /api/aprovar` — Aprovar ou recusar conteúdo (session or personal token; capability: approve)
- `POST /api/art` — Gerar e armazenar uma arte (session or personal token; capability: art)
- `POST /api/carousel` — Gerar carrossel com até dez cards (session or personal token; capability: carousel)
- `GET /api/config` — Ler configuração versionada (session or personal token; capability: config_view)
- `POST /api/config` — Criar nova versão de uma configuração (session or personal token; capability: config)
- `GET /api/config/log` — Listar histórico de configurações (session or personal token; capability: config)
- `POST /api/demanda` — Criar demanda editorial (session or personal token; capability: tasks_assign)
- `POST /api/draft` — Salvar rascunho editorial (session or personal token; capability: draft_save)
- `GET /api/email-drafts` — Listar metadados de rascunhos de e-mail (session or personal token; capability: email_drafts_view)
- `DELETE /api/email-drafts/{templateId}` — Excluir exatamente um rascunho com CAS (session or personal token; capability: delete)
- `GET /api/email-drafts/{templateId}` — Consultar um rascunho de e-mail (session or personal token; capability: email_drafts_view)
- `PUT /api/email-drafts/{templateId}` — Criar ou atualizar um rascunho com CAS (session or personal token; capability: email_drafts_edit)
- `POST /api/enviar` — Enviar conteúdo para aprovação (session or personal token; capability: enviar)
- `GET /api/health` — Consultar saúde do serviço (public)
- `GET /api/insights/horarios` — Consultar melhores horários de publicação (session or personal token; capability: analytics)
- `POST /api/jornada/eventos` — Receber eventos do checkout (servidor a servidor) (session or personal token)
- `POST /api/jornada/lead` — Resumo de um lead para o SiteUP CRM (compras, origem e páginas) (session or personal token)
- `POST /api/jornada/perfil` — Consultar o perfil de uma pessoa pelo e-mail (dado pessoal, só Financeiro) (session or personal token; capability: vendas)
- `POST /api/jornada/ses` — Receber eventos de e-mail do SES (SNS) (session or personal token)
- `POST /api/jornada/sincronizar` — Sincronizar a linha do tempo (session or personal token; capability: config)
- `GET /api/lancamentos` — Listar os lançamentos com dashboard (session or personal token; capability: vendas)
- `PUT /api/lancamentos/{projetoId}` — Cadastrar ou editar o dashboard de um projeto (session or personal token; capability: config)
- `GET /api/lancamentos/{projetoId}/compradores` — Listar os compradores de um lançamento (session or personal token; capability: vendas)
- `GET /api/lancamentos/{projetoId}/decisao` — Consultar o painel de decisão de um lançamento (session or personal token; capability: vendas)
- `GET /api/lancamentos/{projetoId}/disparos` — Consultar os disparos de WhatsApp de um lançamento (session or personal token; capability: vendas)
- `GET /api/lancamentos/{projetoId}/funil` — Consultar o funil do CRM de um lançamento (session or personal token; capability: vendas)
- `GET /api/lancamentos/{projetoId}/jornada` — Consultar o funil da linha do tempo de um lançamento (session or personal token; capability: vendas)
- `GET /api/lancamentos/{projetoId}/midia` — Consultar a mídia paga de um lançamento (session or personal token; capability: vendas)
- `GET /api/lancamentos/{projetoId}/origem` — Consultar a origem das vendas de um lançamento (session or personal token; capability: vendas)
- `GET /api/lancamentos/{projetoId}/perfis` — Consultar os perfis agregados de quem mexeu num lançamento (session or personal token; capability: vendas)
- `GET /api/lancamentos/{projetoId}/resumo` — Consultar o painel de um lançamento (session or personal token; capability: vendas)
- `GET /api/lancamentos/{projetoId}/saude` — Consultar a saúde de um lançamento (session or personal token; capability: vendas)
- `POST /api/mcp` — Chamar o MCP Streamable HTTP do Hermes (session or personal token)
- `GET /api/me` — Consultar membro autenticado e capacidades (session or personal token)
- `GET /api/membros` — Listar membros ativos (Supabase session; capability: members)
- `PATCH /api/membros` — Alterar nível de acesso ou permissão financeira (Supabase session; capability: members)
- `POST /api/membros` — Convidar um novo membro (Supabase session; capability: members)
- `DELETE /api/membros/{memberId}` — Revogar acesso e limpar atribuições atuais (Supabase session; capability: members)
- `POST /api/membros/{memberId}/senha` — Definir senha nova para um membro (Supabase session; capability: members)
- `POST /api/orbum/cancelamentos` — Registrar o motivo de saída de um assinante do Orbum (session or personal token; capability: vendas)
- `GET /api/orbum/resumo` — Consultar o painel da assinatura Orbum (session or personal token; capability: vendas)
- `GET /api/orbum/saidas` — Listar quem está saindo do Orbum (session or personal token; capability: vendas)
- `GET /api/plataformas/{platformId}/senha` — Ler a senha de uma plataforma (Supabase session; capability: team_admin)
- `PUT /api/plataformas/{platformId}/senha` — Gravar ou apagar a senha de uma plataforma (Supabase session; capability: team_admin)
- `GET /api/projects` — Listar projetos colaborativos (session or personal token; capability: projects_view)
- `POST /api/projects` — Criar projeto colaborativo vazio (session or personal token; capability: projects_manage)
- `GET /api/projects/{projectId}` — Consultar um projeto e seu token CAS (session or personal token; capability: projects_view)
- `GET /api/projects/{projectId}/operations` — Listar histórico de operações do projeto (session or personal token; capability: projects_audit_view)
- `POST /api/projects/{projectId}/operations` — Aplicar uma operação semântica com CAS (session or personal token; capability: projects_edit by default; projects_manage according to the documented operation type)
- `POST /api/rag` — Buscar contexto e citações no Cérebro (session or personal token; capability: rag)
- `POST /api/reels` — Iniciar geração assíncrona de vídeo (session or personal token; capability: video)
- `GET /api/reels/{id}` — Consultar uma geração de vídeo (session or personal token; capability: reels_view)
- `POST /api/roteiro` — Gerar roteiro com pesquisa e verificação (session or personal token; capability: roteiro)
- `GET /api/skills` — Listar skills publicadas (session or personal token; capability: skills_view)
- `POST /api/skills` — Publicar nova versão de uma skill (session or personal token; capability: config)
- `GET /api/tarefas` — Listar tarefas ativas do membro (session or personal token; capability: tasks_view)
- `POST /api/upload` — Enviar arquivo pronto (session or personal token; capability: art)
- `GET /api/vendas/comercial` — Consultar as vendas do time comercial e a comissão (session or personal token; capability: vendas)
- `GET /api/vendas/resumo` — Consultar o resumo de vendas do período (session or personal token; capability: vendas)
- `GET /media/{id}` — Baixar uma mídia pelo domínio do Hermes (public)
- `GET /oauth/_accounts` — Listar provedores e contas conectadas (session or personal token; capability: connections_view)
- `GET /oauth/tiktok/creator-info` — Consultar restrições do criador no TikTok (session or personal token; capability: connections_view)
- `POST /oauth/tiktok/publish` — Publicar conteúdo no TikTok (session or personal token; capability: publish)
- `GET /oauth/{provider}/callback` — Concluir callback OAuth (public)
- `POST /oauth/{provider}/disconnect` — Desconectar um provedor social (Supabase session; capability: connections)
- `POST /oauth/{provider}/start` — Iniciar autorização OAuth (Supabase session; capability: connections)
- `GET /oauth/{provider}/status` — Exibir diagnóstico HTML da conexão (session or personal token; capability: connections_view)

## Generated artifacts

- https://socialmedia.janvalellam.com.br/api/ai/SKILL.md — Baixar a skill operacional do Hermes.
- https://socialmedia.janvalellam.com.br/api/ai/chatgpt.md — Baixar instruções para ChatGPT.
- https://socialmedia.janvalellam.com.br/api/ai/claude.md — Baixar instruções para Claude.
- https://socialmedia.janvalellam.com.br/api/ai/cursor.mdc — Baixar regras do Cursor.
- https://socialmedia.janvalellam.com.br/api/ai/hermes.mjs — Baixar a CLI Hermes.
- https://socialmedia.janvalellam.com.br/api/ai/llms-full.txt — Baixar a referência completa para LLMs.
- https://socialmedia.janvalellam.com.br/api/ai/llms.txt — Baixar o índice conciso para LLMs.
- https://socialmedia.janvalellam.com.br/api/ai/manifest.json — Baixar o manifesto verificável dos artefatos.
- https://socialmedia.janvalellam.com.br/api/ai/mcp-setup.md — Baixar instruções de conexão MCP.
- https://socialmedia.janvalellam.com.br/api/ai/openapi.json — Baixar o contrato OpenAPI 3.1.
- https://socialmedia.janvalellam.com.br/api/ai/openapi.yaml — Baixar o contrato OpenAPI 3.1 em YAML.
- https://socialmedia.janvalellam.com.br/api/ai/postman.json — Baixar a coleção Postman gerada.
- https://socialmedia.janvalellam.com.br/api/ai/skill.zip — Baixar a skill completa e instalável.

## Detailed operation reference

### GET /api/access/audit

Consultar a trilha de auditoria da API

Exige sessão Supabase de administrador da equipe. Lista eventos recentes de autorização e gestão sem corpo da requisição, Authorization, segredo, hash de token ou conteúdo sensível.

- operationId: `listApiAccessAudit`
- authentication: Supabase session bearer token (session only)
- required capability: `team_admin`

#### Parameters

##### query limit

- required: false
- description: Máximo de eventos recentes.

Schema:

```json
{
  "type": "integer",
  "minimum": 1,
  "maximum": 200,
  "default": 100
}
```

Example:

```json
100
```

##### query member_id

- required: false
- description: Filtrar pelo membro autor do evento.

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"string"
```

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "audit": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "ID do evento de auditoria."
          },
          "occurred_at": {
            "type": "string",
            "description": "Data/hora do evento.",
            "format": "date-time"
          },
          "request_id": {
            "anyOf": [
              {
                "type": "string",
                "description": "Correlação segura da requisição."
              },
              {
                "type": "null"
              }
            ]
          },
          "actor_member_id": {
            "anyOf": [
              {
                "type": "string",
                "description": "Membro autor."
              },
              {
                "type": "null"
              }
            ]
          },
          "actor_user_id": {
            "anyOf": [
              {
                "type": "string",
                "description": "Usuário Supabase autor."
              },
              {
                "type": "null"
              }
            ]
          },
          "token_id": {
            "anyOf": [
              {
                "type": "string",
                "description": "ID de metadados do token pessoal, nunca o segredo ou hash."
              },
              {
                "type": "null"
              }
            ]
          },
          "auth_method": {
            "type": "string",
            "description": "Método de autenticação observado.",
            "enum": [
              "session",
              "personal_token",
              "system",
              "anonymous"
            ]
          },
          "capability": {
            "anyOf": [
              {
                "type": "string",
                "description": "Capability avaliada."
              },
              {
                "type": "null"
              }
            ]
          },
          "action": {
            "type": "string",
            "description": "Ação normalizada."
          },
          "resource_type": {
            "anyOf": [
              {
                "type": "string",
                "description": "Tipo lógico do recurso."
              },
              {
                "type": "null"
              }
            ]
          },
          "resource_id": {
            "anyOf": [
              {
                "type": "string",
                "description": "ID lógico do recurso."
              },
              {
                "type": "null"
              }
            ]
          },
          "outcome": {
            "type": "string",
            "description": "Resultado normalizado.",
            "enum": [
              "allowed",
              "denied",
              "succeeded",
              "failed"
            ]
          },
          "status_code": {
            "anyOf": [
              {
                "type": "integer",
                "description": "Status HTTP relacionado.",
                "minimum": 100,
                "maximum": 599
              },
              {
                "type": "null"
              }
            ]
          },
          "metadata": {
            "type": "object",
            "properties": {},
            "additionalProperties": true
          }
        },
        "required": [
          "id",
          "occurred_at",
          "auth_method",
          "action",
          "outcome",
          "metadata"
        ],
        "description": "Evento sanitizado da trilha de autorização e gestão de acesso à API."
      }
    }
  },
  "required": [
    "audit"
  ]
}
```

Example:

```json
{
  "audit": [
    {
      "id": "id-exemplo",
      "occurred_at": "2026-08-22T15:00:00.000Z",
      "request_id": "request-id-exemplo",
      "actor_member_id": "actor-member-id-exemplo",
      "actor_user_id": "actor-user-id-exemplo",
      "token_id": "token-id-exemplo",
      "auth_method": "session",
      "capability": "string",
      "action": "string",
      "resource_type": "string",
      "resource_id": "resource-id-exemplo",
      "outcome": "allowed",
      "status_code": 100,
      "metadata": {}
    }
  ]
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### GET /api/access/catalog

Consultar o catálogo de rotas e ferramentas MCP (Central da API)

Catálogo da Central da API: todas as rotas do contrato com área, permissão exigida, nível mínimo que a tem (ou a flag Financeiro), se é só de sessão ou webhook, os parâmetros de caminho e de query e o nome da ferramenta MCP equivalente. Sai do mesmo contrato que gera o MCP. Só administradores, por sessão do Studio.

- operationId: `getApiCatalog`
- authentication: Supabase session bearer token (session only)
- required capability: `team_admin`

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "total": {
      "type": "integer",
      "description": "Rotas no contrato."
    },
    "com_ferramenta": {
      "type": "integer",
      "description": "Rotas com ferramenta MCP."
    },
    "mcp_url": {
      "type": "string",
      "description": "Endereço do MCP."
    },
    "rotas": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {},
        "additionalProperties": true
      },
      "description": "Uma entrada por rota."
    }
  },
  "required": [
    "total",
    "rotas"
  ],
  "additionalProperties": true
}
```

Example:

```json
{
  "total": 1,
  "com_ferramenta": 1,
  "mcp_url": "https://socialmedia.janvalellam.com.br/media/media-id?exp=1790000000&sig=assinatura",
  "rotas": [
    {}
  ]
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### GET /api/access/me

Consultar o próprio acesso individual à API

Exige sessão Supabase interativa e nunca aceita token pessoal. Retorna a configuração destinada aos tokens pessoais do membro, o nível efetivo limitado pelo cargo do Studio e a contagem de tokens ativos; essa configuração não limita a própria sessão.

- operationId: `getMyApiAccess`
- authentication: Supabase session bearer token (session only)

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "member": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "ID do membro."
        },
        "name": {
          "type": "string",
          "description": "Nome."
        },
        "email": {
          "anyOf": [
            {
              "type": "string",
              "description": "E-mail.",
              "format": "email"
            },
            {
              "type": "null"
            }
          ]
        },
        "access_level": {
          "type": "string",
          "description": "Cargo atual no Studio; governa a sessão e funciona como teto do PAT.",
          "enum": [
            "criador",
            "lider",
            "admin"
          ]
        },
        "financeiro": {
          "type": "boolean",
          "description": "Permissão por pessoa: vê o painel de Vendas."
        },
        "api_access_level": {
          "type": "string",
          "description": "Nível individual configurável somente para tokens pessoais da API; não limita sessões do Studio.",
          "enum": [
            "nenhum",
            "leitor",
            "criador",
            "lider",
            "admin"
          ]
        },
        "effective_api_access_level": {
          "type": "string",
          "description": "Nível individual configurável somente para tokens pessoais da API; não limita sessões do Studio.",
          "enum": [
            "nenhum",
            "leitor",
            "criador",
            "lider",
            "admin"
          ]
        }
      },
      "required": [
        "id",
        "name",
        "access_level",
        "api_access_level",
        "effective_api_access_level"
      ],
      "description": "Resumo da configuração de tokens pessoais do membro; não limita a sessão atual do Studio."
    },
    "capabilities": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "Capability efetiva disponível para novos tokens."
      }
    },
    "token_count": {
      "type": "integer",
      "description": "Quantidade de tokens pessoais ativos.",
      "minimum": 0,
      "maximum": 10
    }
  },
  "required": [
    "member",
    "capabilities",
    "token_count"
  ]
}
```

Example:

```json
{
  "member": {
    "id": "id-exemplo",
    "name": "Exemplo Hermes",
    "email": "membro@example.com",
    "access_level": "criador",
    "financeiro": true,
    "api_access_level": "nenhum",
    "effective_api_access_level": "nenhum"
  },
  "capabilities": [
    "string"
  ],
  "token_count": 0
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### GET /api/access/members

Listar acessos individuais da equipe

Exige sessão Supabase de administrador da equipe. Lista membros ativos, cargo do Studio e configuração exclusiva dos tokens pessoais, capabilities efetivas de PAT e metadados de tokens, sem segredo ou hash.

- operationId: `listApiAccessMembers`
- authentication: Supabase session bearer token (session only)
- required capability: `team_admin`

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "levels": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "Nível individual configurável somente para tokens pessoais da API; não limita sessões do Studio.",
        "enum": [
          "nenhum",
          "leitor",
          "criador",
          "lider",
          "admin"
        ]
      },
      "description": "Níveis configuráveis em ordem crescente."
    },
    "members": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "ID do membro."
          },
          "name": {
            "type": "string",
            "description": "Nome."
          },
          "email": {
            "anyOf": [
              {
                "type": "string",
                "description": "E-mail.",
                "format": "email"
              },
              {
                "type": "null"
              }
            ]
          },
          "access_level": {
            "type": "string",
            "description": "Cargo atual no Studio; governa sessões e funciona como teto do PAT.",
            "enum": [
              "criador",
              "lider",
              "admin"
            ]
          },
          "api_access_level": {
            "type": "string",
            "description": "Nível individual configurável somente para tokens pessoais da API; não limita sessões do Studio.",
            "enum": [
              "nenhum",
              "leitor",
              "criador",
              "lider",
              "admin"
            ]
          },
          "effective_api_access_level": {
            "type": "string",
            "description": "Nível individual configurável somente para tokens pessoais da API; não limita sessões do Studio.",
            "enum": [
              "nenhum",
              "leitor",
              "criador",
              "lider",
              "admin"
            ]
          },
          "capabilities": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "Capability efetiva disponível para tokens pessoais; não descreve nem limita a sessão do Studio."
            }
          },
          "token_count": {
            "type": "integer",
            "description": "Quantidade de tokens ativos.",
            "minimum": 0,
            "maximum": 10
          },
          "tokens": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "ID público usado para revogação."
                },
                "label": {
                  "type": "string",
                  "description": "Nome legível definido pelo usuário."
                },
                "prefix": {
                  "type": "string",
                  "description": "Prefixo identificável sem a parte secreta.",
                  "pattern": "^hms_live_[A-Za-z0-9_-]{16}$"
                },
                "scopes": {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "description": "Capability concedida ao token."
                  },
                  "description": "Scopes persistidos em ordem determinística."
                },
                "created_at": {
                  "type": "string",
                  "description": "Criação ISO.",
                  "format": "date-time"
                },
                "expires_at": {
                  "type": "string",
                  "description": "Expiração ISO.",
                  "format": "date-time"
                },
                "last_used_at": {
                  "anyOf": [
                    {
                      "type": "string",
                      "description": "Último uso observado, atualizado de forma best effort.",
                      "format": "date-time"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "revoked_at": {
                  "anyOf": [
                    {
                      "type": "string",
                      "description": "Revogação ISO, quando aplicável.",
                      "format": "date-time"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "status": {
                  "type": "string",
                  "description": "Estado derivado no momento da leitura.",
                  "enum": [
                    "active",
                    "expired",
                    "revoked"
                  ]
                }
              },
              "required": [
                "id",
                "label",
                "prefix",
                "scopes",
                "created_at",
                "expires_at",
                "last_used_at",
                "revoked_at",
                "status"
              ],
              "description": "Metadados revogáveis de um token pessoal sem segredo nem hash."
            }
          }
        },
        "required": [
          "id",
          "name",
          "access_level",
          "api_access_level",
          "effective_api_access_level",
          "capabilities",
          "token_count",
          "tokens"
        ],
        "description": "Visão administrativa do cargo do Studio e da camada separada de tokens pessoais de um membro ativo."
      }
    }
  },
  "required": [
    "levels",
    "members"
  ]
}
```

Example:

```json
{
  "levels": [
    "nenhum"
  ],
  "members": [
    {
      "id": "id-exemplo",
      "name": "Exemplo Hermes",
      "email": "membro@example.com",
      "access_level": "criador",
      "api_access_level": "nenhum",
      "effective_api_access_level": "nenhum",
      "capabilities": [
        "string"
      ],
      "token_count": 0,
      "tokens": [
        {
          "id": "id-exemplo",
          "label": "string",
          "prefix": "string",
          "scopes": [
            "string"
          ],
          "created_at": "2026-08-22T15:00:00.000Z",
          "expires_at": "2026-08-22T15:00:00.000Z",
          "last_used_at": "2026-08-22T15:00:00.000Z",
          "revoked_at": "2026-08-22T15:00:00.000Z",
          "status": "active"
        }
      ]
    }
  ]
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### PATCH /api/access/members/{memberId}

Alterar o nível individual de API de um membro

Exige sessão Supabase de administrador da equipe. O nível da API nunca pode superar o cargo atual no Studio; rebaixamentos reduzem permissões imediatamente e `nenhum` revoga todos os tokens ativos.

- operationId: `updateMemberApiAccess`
- authentication: Supabase session bearer token (session only)
- required capability: `team_admin`

#### Parameters

##### path memberId

- required: true
- description: ID de team_members.

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"string"
```

#### Request body

- required: true
- description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema.

##### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "api_access_level": {
      "type": "string",
      "description": "Nível individual configurável somente para tokens pessoais da API; não limita sessões do Studio.",
      "enum": [
        "nenhum",
        "leitor",
        "criador",
        "lider",
        "admin"
      ]
    }
  },
  "required": [
    "api_access_level"
  ]
}
```

Example:

```json
{
  "api_access_level": "leitor"
}
```

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Atualização concluída."
    },
    "member": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "ID do membro."
        },
        "name": {
          "type": "string",
          "description": "Nome."
        },
        "email": {
          "anyOf": [
            {
              "type": "string",
              "description": "E-mail.",
              "format": "email"
            },
            {
              "type": "null"
            }
          ]
        },
        "access_level": {
          "type": "string",
          "description": "Cargo atual no Studio; governa sessões e funciona como teto do PAT.",
          "enum": [
            "criador",
            "lider",
            "admin"
          ]
        },
        "api_access_level": {
          "type": "string",
          "description": "Nível individual configurável somente para tokens pessoais da API; não limita sessões do Studio.",
          "enum": [
            "nenhum",
            "leitor",
            "criador",
            "lider",
            "admin"
          ]
        },
        "effective_api_access_level": {
          "type": "string",
          "description": "Nível individual configurável somente para tokens pessoais da API; não limita sessões do Studio.",
          "enum": [
            "nenhum",
            "leitor",
            "criador",
            "lider",
            "admin"
          ]
        },
        "capabilities": {
          "type": "array",
          "items": {
            "type": "string",
            "description": "Capability efetiva disponível para tokens pessoais; não descreve nem limita a sessão do Studio."
          }
        },
        "token_count": {
          "type": "integer",
          "description": "Quantidade de tokens ativos.",
          "minimum": 0,
          "maximum": 10
        },
        "tokens": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "ID público usado para revogação."
              },
              "label": {
                "type": "string",
                "description": "Nome legível definido pelo usuário."
              },
              "prefix": {
                "type": "string",
                "description": "Prefixo identificável sem a parte secreta.",
                "pattern": "^hms_live_[A-Za-z0-9_-]{16}$"
              },
              "scopes": {
                "type": "array",
                "items": {
                  "type": "string",
                  "description": "Capability concedida ao token."
                },
                "description": "Scopes persistidos em ordem determinística."
              },
              "created_at": {
                "type": "string",
                "description": "Criação ISO.",
                "format": "date-time"
              },
              "expires_at": {
                "type": "string",
                "description": "Expiração ISO.",
                "format": "date-time"
              },
              "last_used_at": {
                "anyOf": [
                  {
                    "type": "string",
                    "description": "Último uso observado, atualizado de forma best effort.",
                    "format": "date-time"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "revoked_at": {
                "anyOf": [
                  {
                    "type": "string",
                    "description": "Revogação ISO, quando aplicável.",
                    "format": "date-time"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "status": {
                "type": "string",
                "description": "Estado derivado no momento da leitura.",
                "enum": [
                  "active",
                  "expired",
                  "revoked"
                ]
              }
            },
            "required": [
              "id",
              "label",
              "prefix",
              "scopes",
              "created_at",
              "expires_at",
              "last_used_at",
              "revoked_at",
              "status"
            ],
            "description": "Metadados revogáveis de um token pessoal sem segredo nem hash."
          }
        }
      },
      "required": [
        "id",
        "name",
        "access_level",
        "api_access_level",
        "effective_api_access_level",
        "capabilities",
        "token_count",
        "tokens"
      ],
      "description": "Visão administrativa do cargo do Studio e da camada separada de tokens pessoais de um membro ativo."
    }
  },
  "required": [
    "ok",
    "member"
  ]
}
```

Example:

```json
{
  "ok": true,
  "member": {
    "id": "id-exemplo",
    "name": "Exemplo Hermes",
    "email": "membro@example.com",
    "access_level": "criador",
    "api_access_level": "nenhum",
    "effective_api_access_level": "nenhum",
    "capabilities": [
      "string"
    ],
    "token_count": 0,
    "tokens": [
      {
        "id": "id-exemplo",
        "label": "string",
        "prefix": "string",
        "scopes": [
          "string"
        ],
        "created_at": "2026-08-22T15:00:00.000Z",
        "expires_at": "2026-08-22T15:00:00.000Z",
        "last_used_at": "2026-08-22T15:00:00.000Z",
        "revoked_at": "2026-08-22T15:00:00.000Z",
        "status": "active"
      }
    ]
  }
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 404

Recurso não encontrado.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "recurso não encontrado"
}
```

##### 409

Operação conflita com o estado atual.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "conflito"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### DELETE /api/access/members/{memberId}/tokens/{tokenId}

Revogar um token pessoal como administrador

Exige sessão Supabase de administrador da equipe. Revoga exatamente o token indicado de um membro, preservando metadados e trilha de auditoria.

- operationId: `revokeMemberApiToken`
- authentication: Supabase session bearer token (session only)
- required capability: `team_admin`

#### Parameters

##### path memberId

- required: true
- description: ID de team_members.

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"string"
```

##### path tokenId

- required: true
- description: ID público de metadados do token pessoal; nunca é o segredo `hms_live_` nem seu hash.

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"string"
```

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Revogação concluída."
    },
    "token": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "ID público usado para revogação."
        },
        "label": {
          "type": "string",
          "description": "Nome legível definido pelo usuário."
        },
        "prefix": {
          "type": "string",
          "description": "Prefixo identificável sem a parte secreta.",
          "pattern": "^hms_live_[A-Za-z0-9_-]{16}$"
        },
        "scopes": {
          "type": "array",
          "items": {
            "type": "string",
            "description": "Capability concedida ao token."
          },
          "description": "Scopes persistidos em ordem determinística."
        },
        "created_at": {
          "type": "string",
          "description": "Criação ISO.",
          "format": "date-time"
        },
        "expires_at": {
          "type": "string",
          "description": "Expiração ISO.",
          "format": "date-time"
        },
        "last_used_at": {
          "anyOf": [
            {
              "type": "string",
              "description": "Último uso observado, atualizado de forma best effort.",
              "format": "date-time"
            },
            {
              "type": "null"
            }
          ]
        },
        "revoked_at": {
          "anyOf": [
            {
              "type": "string",
              "description": "Revogação ISO, quando aplicável.",
              "format": "date-time"
            },
            {
              "type": "null"
            }
          ]
        },
        "status": {
          "type": "string",
          "description": "Estado derivado no momento da leitura.",
          "enum": [
            "active",
            "expired",
            "revoked"
          ]
        }
      },
      "required": [
        "id",
        "label",
        "prefix",
        "scopes",
        "created_at",
        "expires_at",
        "last_used_at",
        "revoked_at",
        "status"
      ],
      "description": "Metadados revogáveis de um token pessoal sem segredo nem hash."
    }
  },
  "required": [
    "ok",
    "token"
  ]
}
```

Example:

```json
{
  "ok": true,
  "token": {
    "id": "id-exemplo",
    "label": "string",
    "prefix": "string",
    "scopes": [
      "string"
    ],
    "created_at": "2026-08-22T15:00:00.000Z",
    "expires_at": "2026-08-22T15:00:00.000Z",
    "last_used_at": "2026-08-22T15:00:00.000Z",
    "revoked_at": "2026-08-22T15:00:00.000Z",
    "status": "active"
  }
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 404

Recurso não encontrado.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "recurso não encontrado"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### GET /api/access/tokens

Listar os próprios tokens pessoais

Exige sessão Supabase interativa. Lista somente metadados dos tokens pessoais do próprio membro; o valor secreto e o hash nunca são retornados.

- operationId: `listMyApiTokens`
- authentication: Supabase session bearer token (session only)

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "tokens": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "ID público usado para revogação."
          },
          "label": {
            "type": "string",
            "description": "Nome legível definido pelo usuário."
          },
          "prefix": {
            "type": "string",
            "description": "Prefixo identificável sem a parte secreta.",
            "pattern": "^hms_live_[A-Za-z0-9_-]{16}$"
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "Capability concedida ao token."
            },
            "description": "Scopes persistidos em ordem determinística."
          },
          "created_at": {
            "type": "string",
            "description": "Criação ISO.",
            "format": "date-time"
          },
          "expires_at": {
            "type": "string",
            "description": "Expiração ISO.",
            "format": "date-time"
          },
          "last_used_at": {
            "anyOf": [
              {
                "type": "string",
                "description": "Último uso observado, atualizado de forma best effort.",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ]
          },
          "revoked_at": {
            "anyOf": [
              {
                "type": "string",
                "description": "Revogação ISO, quando aplicável.",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ]
          },
          "status": {
            "type": "string",
            "description": "Estado derivado no momento da leitura.",
            "enum": [
              "active",
              "expired",
              "revoked"
            ]
          }
        },
        "required": [
          "id",
          "label",
          "prefix",
          "scopes",
          "created_at",
          "expires_at",
          "last_used_at",
          "revoked_at",
          "status"
        ],
        "description": "Metadados revogáveis de um token pessoal sem segredo nem hash."
      }
    }
  },
  "required": [
    "tokens"
  ]
}
```

Example:

```json
{
  "tokens": [
    {
      "id": "id-exemplo",
      "label": "string",
      "prefix": "string",
      "scopes": [
        "string"
      ],
      "created_at": "2026-08-22T15:00:00.000Z",
      "expires_at": "2026-08-22T15:00:00.000Z",
      "last_used_at": "2026-08-22T15:00:00.000Z",
      "revoked_at": "2026-08-22T15:00:00.000Z",
      "status": "active"
    }
  ]
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### POST /api/access/tokens

Criar um token pessoal com escopo e expiração

Exige sessão Supabase interativa. Cria um token pessoal com validade de 1 a 90 dias e scopes dentro do acesso efetivo. O segredo `hms_live_` aparece uma única vez nesta resposta e não pode ser recuperado depois.

- operationId: `createMyApiToken`
- authentication: Supabase session bearer token (session only)

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

- required: true
- description: Defina um rótulo, validade entre 1 e 90 dias e, opcionalmente, scopes dentro do acesso efetivo. Se scopes for omitido, o servidor usa todas as capabilities atuais.

##### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "label": {
      "type": "string",
      "description": "Nome legível do uso ou dispositivo.",
      "minLength": 1,
      "maxLength": 80
    },
    "scopes": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "Capability solicitada.",
        "pattern": "^[a-z][a-z0-9_.:-]{0,79}$"
      },
      "description": "Subconjunto opcional das capabilities efetivas.",
      "minItems": 1,
      "maxItems": 64,
      "uniqueItems": true
    },
    "expiresInDays": {
      "type": "integer",
      "description": "Validade do token em dias; padrão 30.",
      "minimum": 1,
      "maximum": 90,
      "default": 30
    },
    "expires_in_days": {
      "type": "integer",
      "description": "Alias compatível de expiresInDays; prefira expiresInDays em novos clientes.",
      "minimum": 1,
      "maximum": 90,
      "deprecated": true
    }
  },
  "required": [
    "label"
  ]
}
```

Example:

```json
{
  "label": "Automação editorial",
  "scopes": [
    "projects_view",
    "projects_edit"
  ],
  "expiresInDays": 30
}
```

#### Responses

##### 201

Token criado. O campo token aparece somente nesta resposta e deve ser guardado imediatamente.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "token": {
      "type": "string",
      "description": "Segredo pessoal exibido uma única vez.",
      "pattern": "^hms_live_[A-Za-z0-9_-]{16}\\.[A-Za-z0-9_-]{43}$",
      "x-sensitive": true
    },
    "metadata": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "ID público usado para revogação."
        },
        "label": {
          "type": "string",
          "description": "Nome legível definido pelo usuário."
        },
        "prefix": {
          "type": "string",
          "description": "Prefixo identificável sem a parte secreta.",
          "pattern": "^hms_live_[A-Za-z0-9_-]{16}$"
        },
        "scopes": {
          "type": "array",
          "items": {
            "type": "string",
            "description": "Capability concedida ao token."
          },
          "description": "Scopes persistidos em ordem determinística."
        },
        "created_at": {
          "type": "string",
          "description": "Criação ISO.",
          "format": "date-time"
        },
        "expires_at": {
          "type": "string",
          "description": "Expiração ISO.",
          "format": "date-time"
        },
        "last_used_at": {
          "anyOf": [
            {
              "type": "string",
              "description": "Último uso observado, atualizado de forma best effort.",
              "format": "date-time"
            },
            {
              "type": "null"
            }
          ]
        },
        "revoked_at": {
          "anyOf": [
            {
              "type": "string",
              "description": "Revogação ISO, quando aplicável.",
              "format": "date-time"
            },
            {
              "type": "null"
            }
          ]
        },
        "status": {
          "type": "string",
          "description": "Estado derivado no momento da leitura.",
          "enum": [
            "active",
            "expired",
            "revoked"
          ]
        }
      },
      "required": [
        "id",
        "label",
        "prefix",
        "scopes",
        "created_at",
        "expires_at",
        "last_used_at",
        "revoked_at",
        "status"
      ],
      "description": "Metadados revogáveis de um token pessoal sem segredo nem hash."
    }
  },
  "required": [
    "token",
    "metadata"
  ]
}
```

Example:

```json
{
  "token": "hms_live_<selector>.<secret-shown-once>",
  "metadata": {
    "id": "token-id",
    "label": "Automação editorial",
    "prefix": "hms_live_EXAMPLE123456789",
    "scopes": [
      "projects_view",
      "projects_edit"
    ],
    "created_at": "2026-08-22T12:00:00.000Z",
    "expires_at": "2026-09-21T12:00:00.000Z",
    "last_used_at": null,
    "revoked_at": null,
    "status": "active"
  }
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 429

Limite de dez tokens ativos por usuário atingido.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "cada usuario pode manter no maximo 10 tokens ativos",
  "code": "API_TOKEN_LIMIT"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### DELETE /api/access/tokens/{tokenId}

Revogar um token pessoal próprio

Exige sessão Supabase interativa. Revoga um token do próprio membro de forma idempotente; somente metadados seguros permanecem disponíveis para auditoria.

- operationId: `revokeMyApiToken`
- authentication: Supabase session bearer token (session only)

#### Parameters

##### path tokenId

- required: true
- description: ID público de metadados do token pessoal; nunca é o segredo `hms_live_` nem seu hash.

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"string"
```

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Revogação concluída."
    },
    "token": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "ID público usado para revogação."
        },
        "label": {
          "type": "string",
          "description": "Nome legível definido pelo usuário."
        },
        "prefix": {
          "type": "string",
          "description": "Prefixo identificável sem a parte secreta.",
          "pattern": "^hms_live_[A-Za-z0-9_-]{16}$"
        },
        "scopes": {
          "type": "array",
          "items": {
            "type": "string",
            "description": "Capability concedida ao token."
          },
          "description": "Scopes persistidos em ordem determinística."
        },
        "created_at": {
          "type": "string",
          "description": "Criação ISO.",
          "format": "date-time"
        },
        "expires_at": {
          "type": "string",
          "description": "Expiração ISO.",
          "format": "date-time"
        },
        "last_used_at": {
          "anyOf": [
            {
              "type": "string",
              "description": "Último uso observado, atualizado de forma best effort.",
              "format": "date-time"
            },
            {
              "type": "null"
            }
          ]
        },
        "revoked_at": {
          "anyOf": [
            {
              "type": "string",
              "description": "Revogação ISO, quando aplicável.",
              "format": "date-time"
            },
            {
              "type": "null"
            }
          ]
        },
        "status": {
          "type": "string",
          "description": "Estado derivado no momento da leitura.",
          "enum": [
            "active",
            "expired",
            "revoked"
          ]
        }
      },
      "required": [
        "id",
        "label",
        "prefix",
        "scopes",
        "created_at",
        "expires_at",
        "last_used_at",
        "revoked_at",
        "status"
      ],
      "description": "Metadados revogáveis de um token pessoal sem segredo nem hash."
    }
  },
  "required": [
    "ok",
    "token"
  ]
}
```

Example:

```json
{
  "ok": true,
  "token": {
    "id": "id-exemplo",
    "label": "string",
    "prefix": "string",
    "scopes": [
      "string"
    ],
    "created_at": "2026-08-22T15:00:00.000Z",
    "expires_at": "2026-08-22T15:00:00.000Z",
    "last_used_at": "2026-08-22T15:00:00.000Z",
    "revoked_at": "2026-08-22T15:00:00.000Z",
    "status": "active"
  }
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 404

Recurso não encontrado.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "recurso não encontrado"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### GET /api/ai/SKILL.md

Baixar a skill operacional do Hermes

Instruções de operação segura, roteamento de repositórios e deploy.

Instruções operacionais da skill oficial do Hermes. Use o ZIP quando quiser instalar também referências, metadados e scripts auxiliares.

- operationId: `getAiSkill`
- authentication: public

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Skill Markdown.

###### text/markdown

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"# Hermes Publisher\n\nDocumentação gerada.\n"
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

##### 503

Artefato ausente no build.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "artefato de IA indisponivel"
}
```

### GET /api/ai/chatgpt.md

Baixar instruções para ChatGPT

Instruções para projetos e GPTs que operam o Hermes, incluindo limites de segurança, CAS e confirmação de ações destrutivas.

- operationId: `getAiChatGptInstructions`
- authentication: public

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Instruções ChatGPT.

###### text/markdown

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"# Hermes Publisher\n\nDocumentação gerada.\n"
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

##### 503

Artefato ausente no build.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "artefato de IA indisponivel"
}
```

### GET /api/ai/claude.md

Baixar instruções para Claude

Instruções de projeto para Claude, geradas da mesma versão do contrato público.

- operationId: `getAiClaudeInstructions`
- authentication: public

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Instruções Claude.

###### text/markdown

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"# Hermes Publisher\n\nDocumentação gerada.\n"
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

##### 503

Artefato ausente no build.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "artefato de IA indisponivel"
}
```

### GET /api/ai/cursor.mdc

Baixar regras do Cursor

Regras de projeto para configurar o Cursor com o contrato e as práticas seguras do Hermes.

- operationId: `getAiCursorRules`
- authentication: public

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Cursor Rules.

###### text/plain

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"Operação concluída."
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

##### 503

Artefato ausente no build.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "artefato de IA indisponivel"
}
```

### GET /api/ai/hermes.mjs

Baixar a CLI Hermes

CLI Node.js sem dependências externas para autenticar por sessão Supabase, consultar o manifesto e instalar artefatos oficiais com verificação de integridade. Tokens pessoais são destinados ao HTTP/MCP e não são gravados automaticamente pela CLI.

- operationId: `getAiCli`
- authentication: public

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

CLI Node.js.

###### text/javascript

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"#!/usr/bin/env node\n// Hermes CLI\n"
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

##### 503

Artefato ausente no build.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "artefato de IA indisponivel"
}
```

### GET /api/ai/llms-full.txt

Baixar a referência completa para LLMs

Referência expandida para LLMs, com referências locais resolvidas, corpos de requisição, respostas e exemplos de todas as operações.

- operationId: `getAiLlmsFull`
- authentication: public

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Operações e schemas completos gerados do OpenAPI.

###### text/plain

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"Operação concluída."
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

##### 503

Artefato ausente no build.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "artefato de IA indisponivel"
}
```

### GET /api/ai/llms.txt

Baixar o índice conciso para LLMs

Índice curto, em texto puro, para descoberta por agentes. Ele aponta para o contrato completo e resume as operações disponíveis.

- operationId: `getAiLlms`
- authentication: public

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Índice conciso gerado do OpenAPI.

###### text/plain

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"Operação concluída."
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

##### 503

Artefato ausente no build.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "artefato de IA indisponivel"
}
```

### GET /api/ai/manifest.json

Baixar o manifesto verificável dos artefatos

Lista cada artefato público com URL, MIME type, tamanho e SHA-256. É a fonte para downloads verificáveis e atualização automatizada.

- operationId: `getAiManifest`
- authentication: public

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Manifesto com versão, tamanho e SHA-256.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "schema_version": {
      "type": "integer",
      "description": "Versão do formato.",
      "const": 1
    },
    "release": {
      "type": "object",
      "properties": {
        "version": {
          "type": "string",
          "description": "Versão da camada de IA."
        },
        "date": {
          "type": "string",
          "description": "Data ISO.",
          "format": "date"
        }
      },
      "required": [
        "version",
        "date"
      ]
    },
    "artifacts": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "ID estável."
          },
          "path": {
            "type": "string",
            "description": "Caminho no repositório."
          },
          "url": {
            "type": "string",
            "description": "URL pública.",
            "format": "uri"
          },
          "media_type": {
            "type": "string",
            "description": "MIME."
          },
          "bytes": {
            "type": "integer",
            "description": "Tamanho.",
            "minimum": 1
          },
          "sha256": {
            "type": "string",
            "description": "SHA-256 hexadecimal.",
            "pattern": "^[a-f0-9]{64}$"
          }
        },
        "required": [
          "id",
          "path",
          "url",
          "media_type",
          "bytes",
          "sha256"
        ]
      }
    },
    "skills": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Nome da skill."
          },
          "version": {
            "type": "string",
            "description": "Versão."
          },
          "artifact_id": {
            "type": "string",
            "description": "ID do ZIP."
          },
          "sha256": {
            "type": "string",
            "description": "SHA-256 do ZIP."
          }
        },
        "required": [
          "name",
          "version",
          "artifact_id",
          "sha256"
        ]
      }
    }
  },
  "required": [
    "schema_version",
    "release",
    "artifacts",
    "skills"
  ],
  "description": "Catálogo verificável dos artefatos públicos da camada de IA."
}
```

Example:

```json
{
  "schema_version": 1,
  "release": {
    "version": "string",
    "date": "2026-08-22"
  },
  "artifacts": [
    {
      "id": "id-exemplo",
      "path": "string",
      "url": "https://socialmedia.janvalellam.com.br/media/media-id?exp=1790000000&sig=assinatura",
      "media_type": "string",
      "bytes": 1,
      "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    }
  ],
  "skills": [
    {
      "name": "Exemplo Hermes",
      "version": "string",
      "artifact_id": "artifact-id-exemplo",
      "sha256": "string"
    }
  ]
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

##### 503

Artefato ausente no build.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "artefato de IA indisponivel"
}
```

### GET /api/ai/mcp-setup.md

Baixar instruções de conexão MCP

Guia de conexão ao MCP stateless do Hermes para clientes compatíveis. Use uma sessão Supabase ativa ou um token pessoal `hms_live_` com os scopes exigidos pelas tools.

- operationId: `getAiMcpSetup`
- authentication: public

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Configuração MCP para clientes compatíveis.

###### text/markdown

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"# Hermes Publisher\n\nDocumentação gerada.\n"
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

##### 503

Artefato ausente no build.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "artefato de IA indisponivel"
}
```

### GET /api/ai/openapi.json

Baixar o contrato OpenAPI 3.1

Fonte pública das rotas, autenticação, capabilities, corpos e respostas do Hermes Publisher.

Use este documento como fonte canônica para gerar clientes, validar payloads e descobrir códigos de resposta. O JSON e o YAML descrevem exatamente o mesmo contrato.

- operationId: `getAiOpenApi`
- authentication: public

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Contrato OpenAPI 3.1.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": true
}
```

Example:

```json
{}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

##### 503

Artefato ausente no build.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "artefato de IA indisponivel"
}
```

### GET /api/ai/openapi.yaml

Baixar o contrato OpenAPI 3.1 em YAML

Versão YAML do contrato canônico, indicada para Scalar, Swagger UI, Postman, geradores de SDK e assistentes de código.

- operationId: `getAiOpenApiYaml`
- authentication: public

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Contrato OpenAPI 3.1 em YAML.

###### application/yaml

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"openapi: 3.1.0\ninfo:\n  title: Hermes Publisher API\n"
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

##### 503

Artefato ausente no build.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "artefato de IA indisponivel"
}
```

### GET /api/ai/postman.json

Baixar a coleção Postman gerada

Contém somente placeholders; nenhum token ou segredo é distribuído.

Coleção gerada automaticamente do OpenAPI. Defina `baseUrl` e `accessToken` no ambiente do Postman; o arquivo distribuído não contém credenciais.

- operationId: `getAiPostmanCollection`
- authentication: public

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Postman Collection v2.1.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": true
}
```

Example:

```json
{}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

##### 503

Artefato ausente no build.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "artefato de IA indisponivel"
}
```

### GET /api/ai/skill.zip

Baixar a skill completa e instalável

ZIP determinístico com SKILL.md, agents/openai.yaml, CLI e referências versionadas.

Pacote determinístico da skill oficial. Confira o SHA-256 publicado no manifesto antes de instalar ou atualizar.

- operationId: `getAiSkillZip`
- authentication: public

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Skill ZIP.

###### application/zip

Schema:

```json
{
  "type": "string",
  "contentMediaType": "application/zip"
}
```

Example:

```json
"<arquivo ZIP binário>"
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

##### 503

Artefato ausente no build.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "artefato de IA indisponivel"
}
```

### GET /api/anexaveis

Listar eventos que aceitam mídia do membro

Lista eventos nos quais o membro pode anexar mídia, já acompanhados das referências atualmente persistidas.

- operationId: `listAttachableEvents`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `art`

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "eventos": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Identificador do evento."
          },
          "api_revision": {
            "type": "integer",
            "description": "Token CAS da API; releia o evento antes de toda mutação.",
            "minimum": 0
          },
          "clickup_id": {
            "anyOf": [
              {
                "type": "string",
                "description": "Identificador externo/legado."
              },
              {
                "type": "null"
              }
            ]
          },
          "title": {
            "type": "string",
            "description": "Título editorial."
          },
          "channel": {
            "type": "string",
            "description": "Canal de publicação."
          },
          "status": {
            "type": "string",
            "description": "Estado do fluxo editorial."
          },
          "description": {
            "anyOf": [
              {
                "type": "string",
                "description": "Legenda ou descrição."
              },
              {
                "type": "null"
              }
            ]
          },
          "day": {
            "anyOf": [
              {
                "type": "integer",
                "description": "Dia no horário de Brasília.",
                "minimum": 1,
                "maximum": 31
              },
              {
                "type": "null"
              }
            ]
          },
          "month": {
            "anyOf": [
              {
                "type": "integer",
                "description": "Mês no horário de Brasília.",
                "minimum": 1,
                "maximum": 12
              },
              {
                "type": "null"
              }
            ]
          },
          "year": {
            "anyOf": [
              {
                "type": "integer",
                "description": "Ano no horário de Brasília."
              },
              {
                "type": "null"
              }
            ]
          },
          "due_at": {
            "anyOf": [
              {
                "type": "string",
                "description": "Data/hora ISO 8601 persistida.",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ]
          },
          "editorial_tag": {
            "anyOf": [
              {
                "type": "string",
                "description": "Tipo/tag editorial."
              },
              {
                "type": "null"
              }
            ]
          },
          "assignee_member_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "ID de membro."
            },
            "description": "Responsáveis por ID."
          },
          "assignees_names": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "Nome de membro."
            },
            "description": "Nomes dos responsáveis."
          },
          "media": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "ID."
                },
                "url": {
                  "type": "string",
                  "description": "URL pública no Hermes.",
                  "format": "uri"
                },
                "slide_index": {
                  "type": "integer",
                  "description": "Ordem."
                },
                "kind": {
                  "type": "string",
                  "description": "Tipo lógico."
                }
              },
              "required": [
                "id",
                "url"
              ],
              "additionalProperties": true,
              "description": "Referência pública e ordenável de uma mídia persistida."
            }
          }
        },
        "additionalProperties": true
      }
    }
  },
  "required": [
    "eventos"
  ]
}
```

Example:

```json
{
  "eventos": [
    {
      "id": "id-exemplo",
      "api_revision": 0,
      "clickup_id": "clickup-id-exemplo",
      "title": "Conteúdo editorial",
      "channel": "instagram",
      "status": "processing",
      "description": "Conteúdo de exemplo",
      "day": 1,
      "month": 1,
      "year": 1,
      "due_at": "2026-08-22T15:00:00.000Z",
      "editorial_tag": "string",
      "assignee_member_ids": [
        "assignee-member-id-exemplo"
      ],
      "assignees_names": [
        "Exemplo Hermes"
      ],
      "media": [
        {
          "id": "id-exemplo",
          "url": "https://socialmedia.janvalellam.com.br/media/media-id?exp=1790000000&sig=assinatura",
          "slide_index": 1,
          "kind": "string"
        }
      ]
    }
  ]
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### GET /api/aprovacoes

Listar conteúdos aguardando aprovação

Lista conteúdos aguardando decisão para membros com capability `approve`, incluindo mídias e revisão atual do evento.

- operationId: `listApprovals`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `approve`

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "pendentes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Identificador do evento."
          },
          "api_revision": {
            "type": "integer",
            "description": "Token CAS da API; releia o evento antes de toda mutação.",
            "minimum": 0
          },
          "clickup_id": {
            "anyOf": [
              {
                "type": "string",
                "description": "Identificador externo/legado."
              },
              {
                "type": "null"
              }
            ]
          },
          "title": {
            "type": "string",
            "description": "Título editorial."
          },
          "channel": {
            "type": "string",
            "description": "Canal de publicação."
          },
          "status": {
            "type": "string",
            "description": "Estado do fluxo editorial."
          },
          "description": {
            "anyOf": [
              {
                "type": "string",
                "description": "Legenda ou descrição."
              },
              {
                "type": "null"
              }
            ]
          },
          "day": {
            "anyOf": [
              {
                "type": "integer",
                "description": "Dia no horário de Brasília.",
                "minimum": 1,
                "maximum": 31
              },
              {
                "type": "null"
              }
            ]
          },
          "month": {
            "anyOf": [
              {
                "type": "integer",
                "description": "Mês no horário de Brasília.",
                "minimum": 1,
                "maximum": 12
              },
              {
                "type": "null"
              }
            ]
          },
          "year": {
            "anyOf": [
              {
                "type": "integer",
                "description": "Ano no horário de Brasília."
              },
              {
                "type": "null"
              }
            ]
          },
          "due_at": {
            "anyOf": [
              {
                "type": "string",
                "description": "Data/hora ISO 8601 persistida.",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ]
          },
          "editorial_tag": {
            "anyOf": [
              {
                "type": "string",
                "description": "Tipo/tag editorial."
              },
              {
                "type": "null"
              }
            ]
          },
          "assignee_member_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "ID de membro."
            },
            "description": "Responsáveis por ID."
          },
          "assignees_names": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "Nome de membro."
            },
            "description": "Nomes dos responsáveis."
          },
          "media": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "ID."
                },
                "url": {
                  "type": "string",
                  "description": "URL pública no Hermes.",
                  "format": "uri"
                },
                "slide_index": {
                  "type": "integer",
                  "description": "Ordem."
                },
                "kind": {
                  "type": "string",
                  "description": "Tipo lógico."
                }
              },
              "required": [
                "id",
                "url"
              ],
              "additionalProperties": true,
              "description": "Referência pública e ordenável de uma mídia persistida."
            }
          }
        },
        "additionalProperties": true
      }
    }
  },
  "required": [
    "pendentes"
  ]
}
```

Example:

```json
{
  "pendentes": [
    {
      "id": "id-exemplo",
      "api_revision": 0,
      "clickup_id": "clickup-id-exemplo",
      "title": "Conteúdo editorial",
      "channel": "instagram",
      "status": "processing",
      "description": "Conteúdo de exemplo",
      "day": 1,
      "month": 1,
      "year": 1,
      "due_at": "2026-08-22T15:00:00.000Z",
      "editorial_tag": "string",
      "assignee_member_ids": [
        "assignee-member-id-exemplo"
      ],
      "assignees_names": [
        "Exemplo Hermes"
      ],
      "media": [
        {
          "id": "id-exemplo",
          "url": "https://socialmedia.janvalellam.com.br/media/media-id?exp=1790000000&sig=assinatura",
          "slide_index": 1,
          "kind": "string"
        }
      ]
    }
  ]
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### POST /api/aprovar

Aprovar ou recusar conteúdo

A aprovação é atômica e idempotente no banco; a recusa preserva o conteúdo e muda o status.

Aprova ou recusa o conteúdo sem apagar o histórico. Ao recusar, informe um motivo útil; ao aprovar, a data final pode ser ajustada.

- operationId: `decideApproval`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `approve`

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

- required: true
- description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema.

##### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "event_id": {
      "type": "string",
      "description": "Evento."
    },
    "action": {
      "type": "string",
      "description": "Decisão.",
      "enum": [
        "aprovar",
        "recusar"
      ]
    },
    "motivo": {
      "type": "string",
      "description": "Motivo da recusa."
    },
    "day": {
      "type": "integer",
      "description": "Dia no horário de Brasília.",
      "minimum": 1,
      "maximum": 31
    },
    "month": {
      "type": "integer",
      "description": "Mês no horário de Brasília.",
      "minimum": 1,
      "maximum": 12
    },
    "year": {
      "type": "integer",
      "description": "Ano com quatro dígitos.",
      "minimum": 2000
    },
    "hour": {
      "type": "string",
      "description": "Horário local HH:mm. O padrão do backend é 12:00.",
      "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$"
    },
    "caption": {
      "type": "string",
      "description": "Legenda final opcional."
    }
  },
  "required": [
    "event_id",
    "action"
  ]
}
```

Example:

```json
{
  "event_id": "event-id",
  "action": "aprovar",
  "day": 2,
  "month": 9,
  "year": 2026,
  "hour": "19:00"
}
```

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Sucesso."
    },
    "status": {
      "type": "string",
      "description": "Estado resultante."
    }
  },
  "required": [
    "ok",
    "status"
  ],
  "additionalProperties": true
}
```

Example:

```json
{
  "ok": true,
  "status": "processing"
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 404

Recurso não encontrado.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "recurso não encontrado"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### POST /api/art

Gerar e armazenar uma arte

Gera uma imagem, armazena o resultado e opcionalmente a anexa a um evento acessível. Use `Idempotency-Key` para repetir com segurança após timeout.

- operationId: `generateArt`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `art`

#### Parameters

##### header Idempotency-Key

- required: false
- description: Chave opcional de 8 a 128 caracteres seguros. Repita a mesma chave somente com o mesmo payload; reutilização com conteúdo diferente retorna 409.

Schema:

```json
{
  "type": "string",
  "minLength": 8,
  "maxLength": 128,
  "pattern": "^[A-Za-z0-9._:~-]+$"
}
```

Example:

```json
"docs-20260822-001"
```

#### Request body

- required: true
- description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema.

##### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "prompt": {
      "type": "string",
      "description": "Prompt visual."
    },
    "event_id": {
      "type": "string",
      "description": "Evento opcional."
    },
    "size": {
      "type": "string",
      "description": "Tamanho aceito pelo modelo.",
      "default": "1024x1536"
    },
    "slide_index": {
      "type": "integer",
      "description": "Ordem no evento.",
      "default": 0
    },
    "quality": {
      "type": "string",
      "description": "Qualidade.",
      "default": "medium"
    },
    "kind": {
      "type": "string",
      "description": "Tipo lógico.",
      "default": "imagem"
    },
    "style": {
      "type": "string",
      "description": "Estilo.",
      "default": "epico"
    },
    "format": {
      "type": "string",
      "description": "Proporção.",
      "default": "2:3"
    }
  },
  "required": [
    "prompt"
  ]
}
```

Example:

```json
{
  "prompt": "Céu estrelado em verde profundo",
  "event_id": "event-id"
}
```

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "ID."
    },
    "url": {
      "type": "string",
      "description": "URL pública.",
      "format": "uri"
    },
    "storage_path": {
      "type": "string",
      "description": "Caminho interno sem credenciais."
    }
  },
  "required": [
    "id",
    "url",
    "storage_path"
  ],
  "description": "Resultado de mídia gerada e armazenada pelo Hermes."
}
```

Example:

```json
{
  "id": "id-exemplo",
  "url": "https://socialmedia.janvalellam.com.br/media/media-id?exp=1790000000&sig=assinatura",
  "storage_path": "string"
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 404

Recurso não encontrado.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "recurso não encontrado"
}
```

##### 409

Operação conflita com o estado atual.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "conflito"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### POST /api/carousel

Gerar carrossel com até dez cards

Gera de um a dez cards e os persiste como um conjunto ordenado. Se houver `event_id`, o vínculo de todas as mídias é atômico.

- operationId: `generateCarousel`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `carousel`

#### Parameters

##### header Idempotency-Key

- required: false
- description: Chave opcional de 8 a 128 caracteres seguros. Repita a mesma chave somente com o mesmo payload; reutilização com conteúdo diferente retorna 409.

Schema:

```json
{
  "type": "string",
  "minLength": 8,
  "maxLength": 128,
  "pattern": "^[A-Za-z0-9._:~-]+$"
}
```

Example:

```json
"docs-20260822-001"
```

#### Request body

- required: true
- description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema.

##### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "event_id": {
      "type": "string",
      "description": "Evento opcional."
    },
    "cards": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "text": {
            "type": "string",
            "description": "Texto do card."
          },
          "prompt": {
            "type": "string",
            "description": "Prompt de fundo opcional."
          }
        },
        "required": [
          "text"
        ]
      },
      "description": "Entre 1 e 10 cards.",
      "minItems": 1,
      "maxItems": 10
    }
  },
  "required": [
    "cards"
  ]
}
```

Example:

```json
{
  "event_id": "event-id",
  "cards": [
    {
      "text": "Primeiro insight",
      "prompt": "Cosmos verde escuro"
    }
  ]
}
```

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "cards": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "ID."
          },
          "url": {
            "type": "string",
            "description": "URL pública no Hermes.",
            "format": "uri"
          },
          "slide_index": {
            "type": "integer",
            "description": "Ordem."
          },
          "kind": {
            "type": "string",
            "description": "Tipo lógico."
          }
        },
        "required": [
          "id",
          "url"
        ],
        "additionalProperties": true,
        "description": "Referência pública e ordenável de uma mídia persistida."
      }
    }
  },
  "required": [
    "cards"
  ]
}
```

Example:

```json
{
  "cards": [
    {
      "id": "id-exemplo",
      "url": "https://socialmedia.janvalellam.com.br/media/media-id?exp=1790000000&sig=assinatura",
      "slide_index": 1,
      "kind": "string"
    }
  ]
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 404

Recurso não encontrado.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "recurso não encontrado"
}
```

##### 409

Operação conflita com o estado atual.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "conflito"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### GET /api/config

Ler configuração versionada

Lê o valor mais recente de cada configuração versionada. A resposta inclui a versão para auditoria e diagnóstico.

- operationId: `getConfig`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `config_view`

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "config": {
      "type": "object",
      "properties": {},
      "additionalProperties": {
        "type": "object",
        "properties": {
          "value": {},
          "version": {
            "type": "integer",
            "description": "Versão."
          },
          "updated_at": {
            "anyOf": [
              {
                "type": "string",
                "description": "Atualização ISO.",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "value",
          "version"
        ],
        "description": "Versão mais recente de uma configuração."
      }
    }
  },
  "required": [
    "config"
  ]
}
```

Example:

```json
{
  "config": {}
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### POST /api/config

Criar nova versão de uma configuração

Publica uma nova versão imutável para uma chave de configuração. Exige a capability `config`; versões anteriores permanecem no histórico.

- operationId: `setConfig`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `config`

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

- required: true
- description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema.

##### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "description": "Chave."
    },
    "value": {}
  },
  "required": [
    "key",
    "value"
  ]
}
```

Example:

```json
{
  "key": "horarios",
  "value": {
    "segunda": [
      "12:00"
    ]
  }
}
```

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Sucesso."
    },
    "key": {
      "type": "string",
      "description": "Chave."
    },
    "version": {
      "type": "integer",
      "description": "Nova versão."
    }
  },
  "required": [
    "ok",
    "key",
    "version"
  ]
}
```

Example:

```json
{
  "ok": true,
  "key": "string",
  "version": 1
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### GET /api/config/log

Listar histórico de configurações

Lista o histórico de configurações, opcionalmente filtrado por chave, para auditoria e comparação de versões.

- operationId: `getConfigLog`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `config`

#### Parameters

##### query key

- required: false
- description: Filtrar por chave.

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"string"
```

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "log": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {},
        "additionalProperties": true
      }
    }
  },
  "required": [
    "log"
  ]
}
```

Example:

```json
{
  "log": [
    {}
  ]
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### POST /api/demanda

Criar demanda editorial

Cria uma demanda no calendário e, quando informado, atribui somente um membro ativo. Datas são interpretadas no horário de Brasília.

- operationId: `createDemand`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `tasks_assign`

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

- required: true
- description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema.

##### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "Título."
    },
    "channel": {
      "type": "string",
      "description": "Canal.",
      "default": "instagram"
    },
    "assignee_id": {
      "type": "string",
      "description": "Membro ativo opcional."
    },
    "day": {
      "type": "integer",
      "description": "Dia no horário de Brasília.",
      "minimum": 1,
      "maximum": 31
    },
    "month": {
      "type": "integer",
      "description": "Mês no horário de Brasília.",
      "minimum": 1,
      "maximum": 12
    },
    "year": {
      "type": "integer",
      "description": "Ano com quatro dígitos.",
      "minimum": 2000
    },
    "hour": {
      "type": "string",
      "description": "Horário local HH:mm. O padrão do backend é 12:00.",
      "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$"
    },
    "description": {
      "type": "string",
      "description": "Descrição."
    },
    "tipo": {
      "type": "string",
      "description": "Tag editorial."
    }
  },
  "required": [
    "title"
  ]
}
```

Example:

```json
{
  "title": "Novo corte",
  "channel": "instagram",
  "assignee_id": "member-id",
  "day": 2,
  "month": 9,
  "year": 2026,
  "hour": "12:00"
}
```

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Sucesso."
    },
    "event_id": {
      "type": "string",
      "description": "Evento criado."
    },
    "clickup_id": {
      "type": "string",
      "description": "ID externo."
    },
    "due_at": {
      "anyOf": [
        {
          "type": "string",
          "description": "Data ISO.",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ]
    },
    "event": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Identificador do evento."
        },
        "api_revision": {
          "type": "integer",
          "description": "Token CAS da API; releia o evento antes de toda mutação.",
          "minimum": 0
        },
        "clickup_id": {
          "anyOf": [
            {
              "type": "string",
              "description": "Identificador externo/legado."
            },
            {
              "type": "null"
            }
          ]
        },
        "title": {
          "type": "string",
          "description": "Título editorial."
        },
        "channel": {
          "type": "string",
          "description": "Canal de publicação."
        },
        "status": {
          "type": "string",
          "description": "Estado do fluxo editorial."
        },
        "description": {
          "anyOf": [
            {
              "type": "string",
              "description": "Legenda ou descrição."
            },
            {
              "type": "null"
            }
          ]
        },
        "day": {
          "anyOf": [
            {
              "type": "integer",
              "description": "Dia no horário de Brasília.",
              "minimum": 1,
              "maximum": 31
            },
            {
              "type": "null"
            }
          ]
        },
        "month": {
          "anyOf": [
            {
              "type": "integer",
              "description": "Mês no horário de Brasília.",
              "minimum": 1,
              "maximum": 12
            },
            {
              "type": "null"
            }
          ]
        },
        "year": {
          "anyOf": [
            {
              "type": "integer",
              "description": "Ano no horário de Brasília."
            },
            {
              "type": "null"
            }
          ]
        },
        "due_at": {
          "anyOf": [
            {
              "type": "string",
              "description": "Data/hora ISO 8601 persistida.",
              "format": "date-time"
            },
            {
              "type": "null"
            }
          ]
        },
        "editorial_tag": {
          "anyOf": [
            {
              "type": "string",
              "description": "Tipo/tag editorial."
            },
            {
              "type": "null"
            }
          ]
        },
        "assignee_member_ids": {
          "type": "array",
          "items": {
            "type": "string",
            "description": "ID de membro."
          },
          "description": "Responsáveis por ID."
        },
        "assignees_names": {
          "type": "array",
          "items": {
            "type": "string",
            "description": "Nome de membro."
          },
          "description": "Nomes dos responsáveis."
        }
      },
      "required": [
        "id",
        "title",
        "channel",
        "status"
      ],
      "additionalProperties": true,
      "description": "Evento editorial do calendário com token de revisão CAS."
    }
  },
  "required": [
    "ok",
    "event_id",
    "clickup_id",
    "event"
  ]
}
```

Example:

```json
{
  "ok": true,
  "event_id": "event-id-exemplo",
  "clickup_id": "clickup-id-exemplo",
  "due_at": "2026-08-22T15:00:00.000Z",
  "event": {
    "id": "id-exemplo",
    "api_revision": 0,
    "clickup_id": "clickup-id-exemplo",
    "title": "Conteúdo editorial",
    "channel": "instagram",
    "status": "processing",
    "description": "Conteúdo de exemplo",
    "day": 1,
    "month": 1,
    "year": 1,
    "due_at": "2026-08-22T15:00:00.000Z",
    "editorial_tag": "string",
    "assignee_member_ids": [
      "assignee-member-id-exemplo"
    ],
    "assignees_names": [
      "Exemplo Hermes"
    ]
  }
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 404

Recurso não encontrado.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "recurso não encontrado"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### POST /api/draft

Salvar rascunho editorial

Atualiza legenda e estado editorial usando CAS. Leia o evento imediatamente antes e envie o `api_revision` obtido como `expected_revision`.

- operationId: `saveDraft`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `draft_save`

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

- required: true
- description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema.

##### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "event_id": {
      "type": "string",
      "description": "Evento."
    },
    "expected_revision": {
      "type": "integer",
      "description": "api_revision obtida na leitura mais recente.",
      "minimum": 0
    },
    "caption": {
      "type": "string",
      "description": "Legenda opcional."
    },
    "status": {
      "type": "string",
      "description": "Status.",
      "default": "em progresso"
    }
  },
  "required": [
    "event_id",
    "expected_revision"
  ]
}
```

Example:

```json
{
  "event_id": "event-id",
  "expected_revision": 4,
  "caption": "Nova legenda"
}
```

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Sucesso."
    },
    "status": {
      "type": "string",
      "description": "Status persistido."
    },
    "api_revision": {
      "type": "integer",
      "description": "Nova revisão CAS.",
      "minimum": 0
    }
  },
  "required": [
    "ok",
    "status",
    "api_revision"
  ]
}
```

Example:

```json
{
  "ok": true,
  "status": "processing",
  "api_revision": 0
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 404

Recurso não encontrado.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "recurso não encontrado"
}
```

##### 409

Operação conflita com o estado atual.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "conflito"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### GET /api/email-drafts

Listar metadados de rascunhos de e-mail

A listagem não inclui HTML. Consulte o template individual quando precisar editar.

Lista apenas metadados, sem transferir HTML potencialmente grande. Abra individualmente somente o template que será consultado ou editado.

- operationId: `listEmailDrafts`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `email_drafts_view`

#### Parameters

##### query limit

- required: false
- description: Máximo de rascunhos.

Schema:

```json
{
  "type": "integer",
  "minimum": 1,
  "maximum": 200,
  "default": 100
}
```

Example:

```json
100
```

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "drafts": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "template_id": {
            "type": "string",
            "description": "ID lógico do template."
          },
          "metadata": {
            "type": "object",
            "properties": {},
            "additionalProperties": true
          },
          "updated_at": {
            "type": "string",
            "description": "Token CAS.",
            "format": "date-time"
          },
          "updated_by": {
            "type": "string",
            "description": "Usuário editor."
          }
        },
        "required": [
          "template_id",
          "metadata",
          "updated_at",
          "updated_by"
        ],
        "description": "Metadados leves de um rascunho, sem o HTML completo."
      }
    }
  },
  "required": [
    "drafts"
  ]
}
```

Example:

```json
{
  "drafts": [
    {
      "template_id": "xamanismo-boas-vindas",
      "metadata": {},
      "updated_at": "2026-08-22T15:00:00.000Z",
      "updated_by": "string"
    }
  ]
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### DELETE /api/email-drafts/{templateId}

Excluir exatamente um rascunho com CAS

A exclusão é destrutiva e exige o updated_at atual. Leia o rascunho e confirme o template exato antes de chamar.

Exclusão destrutiva de um único template. Confirme o identificador e envie o `expected_updated_at` atual; conflitos nunca são sobrescritos.

- operationId: `deleteEmailDraft`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `delete`

#### Parameters

##### path templateId

- required: true
- description: ID lógico seguro do template.

Schema:

```json
{
  "type": "string",
  "pattern": "^[A-Za-z0-9._:~-]+$",
  "maxLength": 200
}
```

Example:

```json
"string"
```

##### query expected_updated_at

- required: true
- description: Token CAS da leitura mais recente.

Schema:

```json
{
  "type": "string",
  "format": "date-time"
}
```

Example:

```json
"2026-09-02T15:00:00.000Z"
```

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Sucesso."
    },
    "template_id": {
      "type": "string",
      "description": "Template excluído."
    }
  },
  "required": [
    "ok",
    "template_id"
  ]
}
```

Example:

```json
{
  "ok": true,
  "template_id": "xamanismo-boas-vindas"
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 404

Recurso não encontrado.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "recurso não encontrado"
}
```

##### 409

Operação conflita com o estado atual.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "conflito"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### GET /api/email-drafts/{templateId}

Consultar um rascunho de e-mail

Retorna o HTML completo, metadados e `updated_at`, que funciona como token CAS para a próxima edição ou exclusão.

- operationId: `getEmailDraft`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `email_drafts_view`

#### Parameters

##### path templateId

- required: true
- description: ID lógico seguro do template.

Schema:

```json
{
  "type": "string",
  "pattern": "^[A-Za-z0-9._:~-]+$",
  "maxLength": 200
}
```

Example:

```json
"string"
```

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "draft": {
      "type": "object",
      "properties": {
        "template_id": {
          "type": "string",
          "description": "ID lógico do template."
        },
        "html": {
          "type": "string",
          "description": "HTML completo."
        },
        "metadata": {
          "type": "object",
          "properties": {},
          "additionalProperties": true
        },
        "updated_at": {
          "type": "string",
          "description": "Token CAS.",
          "format": "date-time"
        },
        "updated_by": {
          "type": "string",
          "description": "Usuário editor."
        }
      },
      "required": [
        "template_id",
        "html",
        "metadata",
        "updated_at",
        "updated_by"
      ],
      "description": "Template de e-mail completo com token CAS baseado em timestamp."
    }
  },
  "required": [
    "draft"
  ]
}
```

Example:

```json
{
  "draft": {
    "template_id": "xamanismo-boas-vindas",
    "html": "string",
    "metadata": {},
    "updated_at": "2026-08-22T15:00:00.000Z",
    "updated_by": "string"
  }
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 404

Recurso não encontrado.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "recurso não encontrado"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### PUT /api/email-drafts/{templateId}

Criar ou atualizar um rascunho com CAS

Use expected_updated_at null somente para criar. Para editar, use exatamente o updated_at da leitura mais recente.

Cria ou atualiza um template com CAS. Use `expected_updated_at: null` somente na criação e o timestamp exato da leitura mais recente nas edições.

- operationId: `putEmailDraft`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `email_drafts_edit`

#### Parameters

##### header Idempotency-Key

- required: false
- description: Chave opcional de 8 a 128 caracteres seguros. Repita a mesma chave somente com o mesmo payload; reutilização com conteúdo diferente retorna 409.

Schema:

```json
{
  "type": "string",
  "minLength": 8,
  "maxLength": 128,
  "pattern": "^[A-Za-z0-9._:~-]+$"
}
```

Example:

```json
"docs-20260822-001"
```

##### path templateId

- required: true
- description: ID lógico seguro do template.

Schema:

```json
{
  "type": "string",
  "pattern": "^[A-Za-z0-9._:~-]+$",
  "maxLength": 200
}
```

Example:

```json
"string"
```

#### Request body

- required: true
- description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema.

##### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "html": {
      "type": "string",
      "description": "HTML do e-mail, até 2 MB.",
      "maxLength": 2000000
    },
    "metadata": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    },
    "expected_updated_at": {
      "anyOf": [
        {
          "type": "string",
          "description": "Token CAS da leitura mais recente.",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "html",
    "expected_updated_at"
  ]
}
```

Example:

```json
{
  "html": "<!doctype html><html><body>...</body></html>",
  "metadata": {
    "campaign": "xamanismo"
  },
  "expected_updated_at": null
}
```

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Sucesso."
    },
    "draft": {
      "type": "object",
      "properties": {
        "template_id": {
          "type": "string",
          "description": "ID lógico do template."
        },
        "html": {
          "type": "string",
          "description": "HTML completo."
        },
        "metadata": {
          "type": "object",
          "properties": {},
          "additionalProperties": true
        },
        "updated_at": {
          "type": "string",
          "description": "Token CAS.",
          "format": "date-time"
        },
        "updated_by": {
          "type": "string",
          "description": "Usuário editor."
        }
      },
      "required": [
        "template_id",
        "html",
        "metadata",
        "updated_at",
        "updated_by"
      ],
      "description": "Template de e-mail completo com token CAS baseado em timestamp."
    }
  },
  "required": [
    "ok",
    "draft"
  ]
}
```

Example:

```json
{
  "ok": true,
  "draft": {
    "template_id": "xamanismo-boas-vindas",
    "html": "string",
    "metadata": {},
    "updated_at": "2026-08-22T15:00:00.000Z",
    "updated_by": "string"
  }
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 409

Operação conflita com o estado atual.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "conflito"
}
```

##### 413

HTML excede 2 MB.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "html excede 2 MB",
  "code": "EMAIL_HTML_TOO_LARGE"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### POST /api/enviar

Enviar conteúdo para aprovação

Move um conteúdo editável para o fluxo de aprovação e pode atualizar a data proposta. Exige o `api_revision` mais recente e aceita repetição segura com `Idempotency-Key`.

- operationId: `submitForApproval`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `enviar`

#### Parameters

##### header Idempotency-Key

- required: false
- description: Chave opcional de 8 a 128 caracteres seguros. Repita a mesma chave somente com o mesmo payload; reutilização com conteúdo diferente retorna 409.

Schema:

```json
{
  "type": "string",
  "minLength": 8,
  "maxLength": 128,
  "pattern": "^[A-Za-z0-9._:~-]+$"
}
```

Example:

```json
"docs-20260822-001"
```

#### Request body

- required: true
- description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema.

##### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "event_id": {
      "type": "string",
      "description": "Evento."
    },
    "expected_revision": {
      "type": "integer",
      "description": "api_revision obtida na leitura mais recente.",
      "minimum": 0
    },
    "day": {
      "type": "integer",
      "description": "Dia no horário de Brasília.",
      "minimum": 1,
      "maximum": 31
    },
    "month": {
      "type": "integer",
      "description": "Mês no horário de Brasília.",
      "minimum": 1,
      "maximum": 12
    },
    "year": {
      "type": "integer",
      "description": "Ano com quatro dígitos.",
      "minimum": 2000
    },
    "hour": {
      "type": "string",
      "description": "Horário local HH:mm. O padrão do backend é 12:00.",
      "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$"
    },
    "caption": {
      "type": "string",
      "description": "Legenda."
    },
    "tipo": {
      "type": "string",
      "description": "Tag editorial."
    }
  },
  "required": [
    "event_id",
    "expected_revision"
  ]
}
```

Example:

```json
{
  "event_id": "event-id",
  "expected_revision": 4,
  "day": 2,
  "month": 9,
  "year": 2026,
  "hour": "15:30"
}
```

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Sucesso."
    },
    "status": {
      "type": "string",
      "description": "Sempre para agendar."
    },
    "api_revision": {
      "type": "integer",
      "description": "Nova revisão CAS.",
      "minimum": 0
    },
    "due_at": {
      "anyOf": [
        {
          "type": "string",
          "description": "Data ISO.",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ]
    },
    "proposto": {
      "anyOf": [
        {
          "type": "string",
          "description": "Alias de due_at.",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "ok",
    "status",
    "api_revision"
  ]
}
```

Example:

```json
{
  "ok": true,
  "status": "processing",
  "api_revision": 0,
  "due_at": "2026-08-22T15:00:00.000Z",
  "proposto": "2026-08-22T15:00:00.000Z"
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 404

Recurso não encontrado.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "recurso não encontrado"
}
```

##### 409

Operação conflita com o estado atual.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "conflito"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### GET /api/health

Consultar saúde do serviço

Verificação pública e leve do processo HTTP. Um `200` confirma que o serviço responde; não garante a disponibilidade de cada provedor externo.

- operationId: `getHealth`
- authentication: public

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Indica que o processo HTTP está respondendo."
    },
    "service": {
      "type": "string",
      "description": "Nome do serviço."
    },
    "providers": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "Provedor social registrado no ambiente."
      }
    }
  },
  "required": [
    "ok",
    "service",
    "providers"
  ]
}
```

Example:

```json
{
  "ok": true,
  "service": "hermes-publisher",
  "providers": [
    "meta",
    "youtube"
  ]
}
```

### GET /api/insights/horarios

Consultar melhores horários de publicação

Retorna horários e sinais disponíveis para orientar o planejamento editorial. A origem do cálculo aparece no campo `fonte`.

- operationId: `getPublishingTimes`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `analytics`

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "fonte": {
      "type": "string",
      "description": "Origem do cálculo."
    }
  },
  "required": [
    "fonte"
  ],
  "additionalProperties": true
}
```

Example:

```json
{
  "fonte": "string"
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### POST /api/jornada/eventos

Receber eventos do checkout (servidor a servidor)

Entrada servidor a servidor da linha do tempo: o checkout do Xamanismo avisa quando alguém abre o checkout, muda de etapa ou se identifica. Autentica pelo cabeçalho `x-jornada-token` (segredo compartilhado), não por sessão. Aceita de 1 a 50 eventos; e-mail vira hash e nunca é gravado em claro; eventos repetidos (mesma sessão e id) são ignorados.

- operationId: `ingestJourneyEvents`
- authentication: Supabase session or `hms_live_` personal bearer token

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

- required: true
- description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema.

##### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "eventos": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "evento": {
            "type": "string",
            "description": "abriu_checkout, etapa_checkout, identificou, respondeu_enquete ou visitou_pagina.",
            "enum": [
              "abriu_checkout",
              "etapa_checkout",
              "identificou",
              "respondeu_enquete",
              "visitou_pagina"
            ]
          },
          "sessao": {
            "type": "string",
            "description": "Id da sessão do navegador."
          },
          "id": {
            "type": "string",
            "description": "Id único do evento na sessão."
          },
          "email": {
            "type": "string",
            "description": "Obrigatório em identificou e respondeu_enquete; vira hash."
          },
          "produto": {
            "type": "string",
            "description": "commerce_product."
          },
          "lancamento": {
            "type": "string",
            "description": "launch_id."
          },
          "ocorreu_em": {
            "type": "string",
            "description": "Instante (até 1 dia de diferença).",
            "format": "date-time"
          },
          "detalhe": {
            "type": "object",
            "properties": {},
            "additionalProperties": {
              "type": "string",
              "description": "Chaves permitidas: etapa, pagina, origem, lote, utm_*, votacao, opcao, peso, titulo, site, referencia, gclid e fbclid."
            }
          }
        },
        "required": [
          "evento",
          "sessao",
          "id"
        ]
      },
      "description": "De 1 a 50 eventos."
    }
  },
  "required": [
    "eventos"
  ]
}
```

Example:

```json
{
  "eventos": [
    {
      "evento": "abriu_checkout",
      "sessao": "sess-123456",
      "id": "ev-000001",
      "produto": "curso_kardec"
    }
  ]
}
```

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Sucesso."
    },
    "recebidos": {
      "type": "integer",
      "description": "Eventos recebidos."
    },
    "gravados": {
      "type": "integer",
      "description": "Eventos novos gravados."
    },
    "recusados": {
      "type": "integer",
      "description": "Eventos inválidos ignorados."
    }
  },
  "required": [
    "ok",
    "gravados"
  ]
}
```

Example:

```json
{
  "ok": true,
  "recebidos": 1,
  "gravados": 1,
  "recusados": 1
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### POST /api/jornada/lead

Resumo de um lead para o SiteUP CRM (compras, origem e páginas)

Consulta servidor a servidor da aba Contexto do lead do SiteUP CRM: compras de todas as lojas (checkout do Xamanismo e loja nova), primeiro e último toque (canal, UTMs, página de entrada) e as últimas cinco páginas visitadas. Visita anônima só aparece depois que a pessoa se identificou na mesma sessão. O e-mail vai no corpo, vira hash e não é guardado; nenhum dado de cartão ou documento sai. Token só de leitura (JORNADA_LEAD_TOKEN) no cabeçalho `x-jornada-token`.

- operationId: `getLeadContext`
- authentication: Supabase session or `hms_live_` personal bearer token

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

- required: true
- description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema.

##### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "description": "E-mail do contato. Vira hash e não é guardado.",
      "format": "email"
    }
  },
  "required": [
    "email"
  ]
}
```

Example:

```json
{
  "email": "contato@siteup.com.br"
}
```

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "encontrado": {
      "type": "boolean",
      "description": "Se há eventos dessa pessoa."
    },
    "compras": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {},
        "additionalProperties": true
      },
      "description": "Um item por pedido, do mais novo para o mais antigo: produto, rotulo, valor_centavos, moeda, status (pago, recusado, pendente, vencido, estornado), metodo, parcelas, ocorreu_em, loja (xamanismo, loja-nova ou loja-antiga, que é a Shopify até a virada) e site."
    },
    "total_pago": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    },
    "origem": {
      "anyOf": [
        {
          "type": "object",
          "properties": {},
          "additionalProperties": true
        },
        {
          "type": "null"
        }
      ]
    },
    "paginas": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {},
        "additionalProperties": true
      },
      "description": "Últimas cinco páginas visitadas."
    },
    "paginas_total": {
      "type": "integer",
      "description": "Visitas registradas."
    },
    "paginas_dias": {
      "type": "integer",
      "description": "Dias com visita."
    }
  },
  "required": [
    "encontrado"
  ],
  "additionalProperties": true
}
```

Example:

```json
{
  "encontrado": true,
  "compras": [
    {}
  ],
  "total_pago": {},
  "origem": {},
  "paginas": [
    {}
  ],
  "paginas_total": 1,
  "paginas_dias": 1
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### POST /api/jornada/perfil

Consultar o perfil de uma pessoa pelo e-mail (dado pessoal, só Financeiro)

Perfil de uma pessoa pelo e-mail, enviado no corpo (nunca na URL): segmento, compras, lançamentos em que mexeu, canal e hora preferidos, temas e a sugestão de próximo evento com o motivo. O e-mail só vira hash para a busca e não é guardado. Dado pessoal: exige a capability `vendas` (Financeiro) e a resposta não é cacheada.

- operationId: `getPersonProfile`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `vendas`

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

- required: true
- description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema.

##### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "description": "E-mail da pessoa. Vira hash e não é guardado.",
      "format": "email"
    }
  },
  "required": [
    "email"
  ]
}
```

Example:

```json
{
  "email": "contato@siteup.com.br"
}
```

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "encontrado": {
      "type": "boolean",
      "description": "Se há eventos dessa pessoa."
    },
    "segmento": {
      "type": "string",
      "description": "Segmento."
    },
    "proximo": {
      "anyOf": [
        {
          "type": "object",
          "properties": {},
          "additionalProperties": true
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "encontrado"
  ],
  "additionalProperties": true
}
```

Example:

```json
{
  "encontrado": true,
  "segmento": "string",
  "proximo": {}
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### POST /api/jornada/ses

Receber eventos de e-mail do SES (SNS)

Entrada dos eventos de e-mail do SES (entregue, aberto, clicado, devolvido, reclamação) publicados pelo SNS do configuration set `jve-rastreio`. Autentica pelo `token` na query (JORNADA_SES_TOKEN) e confere o tópico (JORNADA_SES_TOPIC_ARN); confirma a assinatura do SNS só em URL da própria AWS. Grava na linha do tempo por pessoa (hash do e-mail).

- operationId: `ingestSesEvent`
- authentication: Supabase session or `hms_live_` personal bearer token

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

- required: true
- description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema.

##### text/plain

Schema:

```json
{
  "type": "string",
  "description": "Envelope JSON do SNS."
}
```

Example:

```json
"string"
```

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Recebido."
    },
    "status": {
      "type": "string",
      "description": "evento, assinatura_confirmada, ignorado, topico_errado ou invalido."
    }
  },
  "required": [
    "ok"
  ]
}
```

Example:

```json
{
  "ok": true,
  "status": "processing"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### POST /api/jornada/sincronizar

Sincronizar a linha do tempo

Relê as fontes da linha do tempo (pedidos da Pagar.me e da Stripe em todos os status e envios de recuperação do SiteUP CRM) dos últimos `dias` (1 a 120). A mesma sincronização roda sozinha a cada 15 minutos quando `JORNADA_SYNC=on`. Exige a capability `config`.

- operationId: `syncJourney`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `config`

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

- required: true
- description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema.

##### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "dias": {
      "type": "integer",
      "description": "Dias para trás (1 a 120, padrão 3; até 3650 quando fontes é só shopify)."
    },
    "fontes": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "pagarme, stripe, shopify ou crm"
      },
      "description": "Limita as fontes lidas; sem ele lê todas. Use [\"shopify\"] para trazer o histórico da loja antiga."
    }
  }
}
```

Example:

```json
{
  "dias": 30
}
```

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Sucesso."
    },
    "dias": {
      "type": "integer",
      "description": "Dias lidos."
    },
    "gravados": {
      "type": "integer",
      "description": "Eventos novos."
    }
  },
  "required": [
    "ok"
  ],
  "additionalProperties": true
}
```

Example:

```json
{
  "ok": true,
  "dias": 1,
  "gravados": 1
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### GET /api/lancamentos

Listar os lançamentos com dashboard

Lista os lançamentos com dashboard (configuração em hermes_config, chave `lancamentos`; sem ela, os quatro de fábrica) e o projeto do Studio de cada um. Exige a capability `vendas`.

- operationId: `listLaunches`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `vendas`

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "fonte": {
      "type": "string",
      "description": "padrao ou config."
    },
    "avisos": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "Aviso."
      },
      "description": "Configurações ignoradas."
    },
    "lancamentos": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {},
        "additionalProperties": true
      },
      "description": "Lançamentos com o projeto do Studio."
    }
  },
  "required": [
    "fonte",
    "lancamentos"
  ]
}
```

Example:

```json
{
  "fonte": "string",
  "avisos": [
    "string"
  ],
  "lancamentos": [
    {}
  ]
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### PUT /api/lancamentos/{projetoId}

Cadastrar ou editar o dashboard de um projeto

Cadastra ou edita o dashboard de um projeto (grupos de produto, códigos `commerce_product`, `launch_id` opcionais e janela). Grava a lista inteira em hermes_config com nova versão e histórico. Exige a capability `config`.

- operationId: `putLaunch`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `config`

#### Parameters

##### path projetoId

- required: true
- description: ID do projeto em hermes_projects.

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"string"
```

#### Request body

- required: true
- description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema.

##### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "projeto_id": {
      "type": "string",
      "description": "ID do projeto."
    },
    "nome": {
      "type": "string",
      "description": "Nome do lançamento."
    },
    "tipo": {
      "type": "string",
      "description": "Tipo.",
      "enum": [
        "lancamento",
        "perpetuo"
      ]
    },
    "inicio": {
      "anyOf": [
        {
          "type": "string",
          "description": "Primeiro dia (YYYY-MM-DD)."
        },
        {
          "type": "null"
        }
      ]
    },
    "fim": {
      "anyOf": [
        {
          "type": "string",
          "description": "Último dia (YYYY-MM-DD)."
        },
        {
          "type": "null"
        }
      ]
    },
    "grupos": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "chave": {
            "type": "string",
            "description": "Chave do grupo (a-z, 0-9, _)."
          },
          "rotulo": {
            "type": "string",
            "description": "Rótulo exibido."
          },
          "produtos": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "Código commerce_product."
            },
            "description": "Códigos do grupo."
          },
          "launch_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "launch_id aceito."
            },
            "description": "Vazio: conta pela janela de datas."
          }
        },
        "required": [
          "chave",
          "produtos"
        ]
      },
      "description": "Grupos de produto."
    }
  },
  "required": [
    "projeto_id",
    "nome",
    "grupos"
  ]
}
```

Example:

```json
{
  "projeto_id": "ca185d1f-b631-4699-9bbc-4cd81169b6a9",
  "nome": "O Funeral da Evidência",
  "tipo": "lancamento",
  "inicio": "2026-09-01",
  "fim": null,
  "grupos": [
    {
      "chave": "ingressos",
      "rotulo": "Ingressos",
      "produtos": [
        "o_funeral_da_evidencia_ingresso"
      ],
      "launch_ids": [
        "funeral-2026-10"
      ]
    }
  ]
}
```

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Sucesso."
    },
    "version": {
      "type": "integer",
      "description": "Versão gravada."
    },
    "lancamento": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "ok",
    "version"
  ]
}
```

Example:

```json
{
  "ok": true,
  "version": 1,
  "lancamento": {}
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 404

Recurso não encontrado.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "recurso não encontrado"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### GET /api/lancamentos/{projetoId}/compradores

Listar os compradores de um lançamento

Aba Compradores: pedidos pagos do lançamento no período com nome, e-mail, telefone, produto, valor, método e canal, mais recentes primeiro (até 2000). Contém dados pessoais: exige a capability `vendas` (permissão Financeiro) e a resposta nunca é cacheada.

- operationId: `getLaunchBuyers`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `vendas`

#### Parameters

##### path projetoId

- required: true
- description: ID do projeto em hermes_projects.

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"string"
```

##### query aba

- required: false
- description: Aba do lançamento.

Schema:

```json
{
  "type": "string",
  "description": "Chave da aba."
}
```

Example:

```json
"lancamento"
```

##### query from

- required: false
- description: Início do período.

Schema:

```json
{
  "type": "string",
  "description": "Primeiro dia (YYYY-MM-DD).",
  "format": "date"
}
```

Example:

```json
"2026-09-21"
```

##### query to

- required: false
- description: Fim do período.

Schema:

```json
{
  "type": "string",
  "description": "Último dia (YYYY-MM-DD).",
  "format": "date"
}
```

Example:

```json
"2026-09-23"
```

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "description": "ok, sem_config ou nao_configurado."
    }
  },
  "required": [
    "status"
  ],
  "additionalProperties": true
}
```

Example:

```json
{
  "status": "processing"
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 404

Recurso não encontrado.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "recurso não encontrado"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### GET /api/lancamentos/{projetoId}/decisao

Consultar o painel de decisão de um lançamento

Painel de decisão do lançamento: metas escritas no projeto do Studio contra o realizado, ritmo dos últimos dias (sem o dia da abertura) e projeção até o fim; comparação com o lançamento anterior no mesmo dia do ciclo (ingressos, receita, Orbum); custo de mídia (anúncio + WhatsApp) e resultado; quem já era cliente; ingressos que viraram Orbum e por qual caminho; vendas por lote com a hora da virada; e o efeito de cada onda de WhatsApp (recebeu, leu, comprou em 24 h, custo). Só números agregados; exige a capability `vendas`. Cada bloco traz `status` próprio e um erro num bloco não derruba os outros.

- operationId: `getLaunchDecision`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `vendas`

#### Parameters

##### path projetoId

- required: true
- description: ID do projeto em hermes_projects.

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"string"
```

##### query aba

- required: false
- description: Aba do lançamento.

Schema:

```json
{
  "type": "string",
  "description": "Chave da aba."
}
```

Example:

```json
"lancamento"
```

##### query from

- required: false
- description: Início do período.

Schema:

```json
{
  "type": "string",
  "description": "Primeiro dia (YYYY-MM-DD).",
  "format": "date"
}
```

Example:

```json
"2026-09-21"
```

##### query to

- required: false
- description: Fim do período.

Schema:

```json
{
  "type": "string",
  "description": "Último dia (YYYY-MM-DD).",
  "format": "date"
}
```

Example:

```json
"2026-09-23"
```

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "periodo": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    },
    "metas": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    },
    "comparacao": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    },
    "custo": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "periodo",
    "metas"
  ],
  "additionalProperties": true
}
```

Example:

```json
{
  "periodo": {},
  "metas": {},
  "comparacao": {},
  "custo": {}
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 404

Recurso não encontrado.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "recurso não encontrado"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### GET /api/lancamentos/{projetoId}/disparos

Consultar os disparos de WhatsApp de um lançamento

Aba Disparos do lançamento: cada template de WhatsApp cujo nome casa com `disparos.templates` da configuração, com enviadas, entregues, lidas, taxa de leitura e custo (USD da Meta e BRL pela PTAX), prévia da mensagem e vendas atribuídas pelo `utm_content` do botão. Cache de 30 minutos; templates que a Meta não respondeu aparecem em `incompletos`. Exige a capability `vendas`.

- operationId: `getLaunchBroadcasts`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `vendas`

#### Parameters

##### path projetoId

- required: true
- description: ID do projeto em hermes_projects.

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"string"
```

##### query aba

- required: false
- description: Aba do lançamento.

Schema:

```json
{
  "type": "string",
  "description": "Chave da aba."
}
```

Example:

```json
"lancamento"
```

##### query from

- required: false
- description: Início do período.

Schema:

```json
{
  "type": "string",
  "description": "Primeiro dia (YYYY-MM-DD).",
  "format": "date"
}
```

Example:

```json
"2026-09-21"
```

##### query to

- required: false
- description: Fim do período.

Schema:

```json
{
  "type": "string",
  "description": "Último dia (YYYY-MM-DD).",
  "format": "date"
}
```

Example:

```json
"2026-09-23"
```

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "description": "ok, sem_config ou nao_configurado."
    }
  },
  "required": [
    "status"
  ],
  "additionalProperties": true
}
```

Example:

```json
{
  "status": "processing"
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 404

Recurso não encontrado.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "recurso não encontrado"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### GET /api/lancamentos/{projetoId}/funil

Consultar o funil do CRM de um lançamento

Aba Check-in e presença: quantos cards estão em cada etapa do funil do lançamento no SiteUP CRM (config `funil`) e quantos entraram em cada etapa por dia no período. Cache de 5 minutos; exige a capability `vendas`.

- operationId: `getLaunchCrmFunnel`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `vendas`

#### Parameters

##### path projetoId

- required: true
- description: ID do projeto em hermes_projects.

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"string"
```

##### query aba

- required: false
- description: Aba do lançamento.

Schema:

```json
{
  "type": "string",
  "description": "Chave da aba."
}
```

Example:

```json
"lancamento"
```

##### query from

- required: false
- description: Início do período.

Schema:

```json
{
  "type": "string",
  "description": "Primeiro dia (YYYY-MM-DD).",
  "format": "date"
}
```

Example:

```json
"2026-09-21"
```

##### query to

- required: false
- description: Fim do período.

Schema:

```json
{
  "type": "string",
  "description": "Último dia (YYYY-MM-DD).",
  "format": "date"
}
```

Example:

```json
"2026-09-23"
```

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "description": "ok, sem_config ou nao_configurado."
    }
  },
  "required": [
    "status"
  ],
  "additionalProperties": true
}
```

Example:

```json
{
  "status": "processing"
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 404

Recurso não encontrado.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "recurso não encontrado"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### GET /api/lancamentos/{projetoId}/jornada

Consultar o funil da linha do tempo de um lançamento

Funil agregado do lançamento a partir da linha do tempo: pessoas que abriram o checkout, se identificaram, geraram pagamento e compraram, onde cada uma parou, pagamentos recusados e expirados, recuperações enviadas e quem voltou em até 7 dias. Sessões anônimas contam como a pessoa que se identificou nelas. Só números agregados; exige a capability `vendas`.

- operationId: `getLaunchJourney`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `vendas`

#### Parameters

##### path projetoId

- required: true
- description: ID do projeto em hermes_projects.

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"string"
```

##### query aba

- required: false
- description: Aba do lançamento.

Schema:

```json
{
  "type": "string",
  "description": "Chave da aba."
}
```

Example:

```json
"lancamento"
```

##### query from

- required: false
- description: Início do período.

Schema:

```json
{
  "type": "string",
  "description": "Primeiro dia (YYYY-MM-DD).",
  "format": "date"
}
```

Example:

```json
"2026-09-21"
```

##### query to

- required: false
- description: Fim do período.

Schema:

```json
{
  "type": "string",
  "description": "Último dia (YYYY-MM-DD).",
  "format": "date"
}
```

Example:

```json
"2026-09-23"
```

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "pessoas": {
      "type": "integer",
      "description": "Pessoas distintas."
    },
    "passos": {
      "type": "object",
      "properties": {},
      "additionalProperties": {
        "type": "integer",
        "description": "Pessoas que chegaram ao passo."
      }
    }
  },
  "required": [
    "pessoas",
    "passos"
  ],
  "additionalProperties": true
}
```

Example:

```json
{
  "pessoas": 1,
  "passos": {}
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 404

Recurso não encontrado.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "recurso não encontrado"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### GET /api/lancamentos/{projetoId}/midia

Consultar a mídia paga de um lançamento

Aba Mídia do lançamento: gasto em anúncios do Meta e do Google das campanhas cujo nome casa com `midia.campanhas` da configuração, com impressões, cliques, CTR, CPC e CPM por plataforma, por grupo de produto (`midia.produtos`), por campanha (até 50), por anúncio (até 20) e por dia. Fonte: tabelas sincronizadas a cada ~5 h. Valores em reais; exige a capability `vendas`.

- operationId: `getLaunchMedia`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `vendas`

#### Parameters

##### path projetoId

- required: true
- description: ID do projeto em hermes_projects.

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"string"
```

##### query aba

- required: false
- description: Aba do lançamento.

Schema:

```json
{
  "type": "string",
  "description": "Chave da aba."
}
```

Example:

```json
"lancamento"
```

##### query from

- required: false
- description: Início do período.

Schema:

```json
{
  "type": "string",
  "description": "Primeiro dia (YYYY-MM-DD).",
  "format": "date"
}
```

Example:

```json
"2026-09-21"
```

##### query to

- required: false
- description: Fim do período.

Schema:

```json
{
  "type": "string",
  "description": "Último dia (YYYY-MM-DD).",
  "format": "date"
}
```

Example:

```json
"2026-09-23"
```

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "description": "ok, sem_config ou nao_configurado."
    }
  },
  "required": [
    "status"
  ],
  "additionalProperties": true
}
```

Example:

```json
{
  "status": "processing"
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 404

Recurso não encontrado.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "recurso não encontrado"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### GET /api/lancamentos/{projetoId}/origem

Consultar a origem das vendas de um lançamento

Aba Origem do lançamento: vendas pagas agrupadas por canal (derivado do utm_source), campanha (utm_campaign), conteúdo (utm_content) e origem_venda, com receita por moeda. Último clique, pelas marcações que o checkout grava no pedido; vendas da loja Shopify ficam de fora. Exige a capability `vendas`.

- operationId: `getLaunchOrigin`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `vendas`

#### Parameters

##### path projetoId

- required: true
- description: ID do projeto em hermes_projects.

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"string"
```

##### query aba

- required: false
- description: Aba do lançamento.

Schema:

```json
{
  "type": "string",
  "description": "Chave da aba."
}
```

Example:

```json
"lancamento"
```

##### query from

- required: false
- description: Início do período.

Schema:

```json
{
  "type": "string",
  "description": "Primeiro dia (YYYY-MM-DD).",
  "format": "date"
}
```

Example:

```json
"2026-09-21"
```

##### query to

- required: false
- description: Fim do período.

Schema:

```json
{
  "type": "string",
  "description": "Último dia (YYYY-MM-DD).",
  "format": "date"
}
```

Example:

```json
"2026-09-23"
```

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "description": "ok."
    },
    "vendas": {
      "type": "integer",
      "description": "Vendas pagas consideradas."
    }
  },
  "required": [
    "status"
  ],
  "additionalProperties": true
}
```

Example:

```json
{
  "status": "processing",
  "vendas": 1
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 404

Recurso não encontrado.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "recurso não encontrado"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### GET /api/lancamentos/{projetoId}/perfis

Consultar os perfis agregados de quem mexeu num lançamento

Perfis agregados de quem mexeu no lançamento (Fase 4): pessoas por segmento (recorrente, comprador, quase comprou, interessado, só mensagem), canal que mais responde, hora em que mais age (Brasília), assinantes do Orbum, quem comprou em outro lançamento, temas votados e a sugestão de próximo evento com a regra usada. As chaves `funeral` e `funeral-2026-10` contam como o mesmo lançamento. Só contagens, nenhuma pessoa; exige a capability `vendas`.

- operationId: `getLaunchProfiles`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `vendas`

#### Parameters

##### path projetoId

- required: true
- description: ID do projeto em hermes_projects.

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"string"
```

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "description": "ok."
    },
    "pessoas": {
      "type": "integer",
      "description": "Pessoas que mexeram no lançamento."
    },
    "segmentos": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "chave": {
            "type": "string",
            "description": "Segmento."
          },
          "rotulo": {
            "type": "string",
            "description": "Rótulo."
          },
          "pessoas": {
            "type": "integer",
            "description": "Pessoas."
          }
        },
        "required": [
          "chave",
          "pessoas"
        ]
      },
      "description": "Pessoas por segmento."
    },
    "proximo_evento": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {},
        "additionalProperties": true
      },
      "description": "Sugestão de próximo evento, agregada."
    }
  },
  "required": [
    "status",
    "pessoas",
    "segmentos"
  ],
  "additionalProperties": true
}
```

Example:

```json
{
  "status": "processing",
  "pessoas": 1,
  "segmentos": [
    {
      "chave": "string",
      "rotulo": "string",
      "pessoas": 1
    }
  ],
  "proximo_evento": [
    {}
  ]
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 404

Recurso não encontrado.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "recurso não encontrado"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### GET /api/lancamentos/{projetoId}/resumo

Consultar o painel de um lançamento

Painel de um lançamento: vendas por grupo de produto, pagamentos falhos, pendentes e quantos iniciaram o pagamento, lidos ao vivo da Pagar.me e da Stripe por `commerce_product` e `launch_id`. Sem from/to usa a janela do lançamento ou da aba pedida (30 dias no perpétuo), no máximo 400 dias. Abas separam períodos, como pré-venda e lançamento, sem misturar números. Valores desconhecidos vêm como `null`, moedas nunca são somadas e a resposta nunca inclui dados pessoais. Cache de cinco minutos no servidor.

- operationId: `getLaunchSummary`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `vendas`

#### Parameters

##### path projetoId

- required: true
- description: ID do projeto em hermes_projects.

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"string"
```

##### query aba

- required: false
- description: Aba com datas e grupos próprios; padrão é a primeira.

Schema:

```json
{
  "type": "string",
  "description": "Chave da aba do lançamento (ex.: `prevenda_livro`)."
}
```

Example:

```json
"lancamento"
```

##### query from

- required: false
- description: Início do período; padrão é o início do lançamento.

Schema:

```json
{
  "type": "string",
  "description": "Primeiro dia (YYYY-MM-DD, horário de Brasília).",
  "format": "date"
}
```

Example:

```json
"2026-09-01"
```

##### query to

- required: false
- description: Fim do período, no máximo amanhã.

Schema:

```json
{
  "type": "string",
  "description": "Último dia (YYYY-MM-DD, horário de Brasília).",
  "format": "date"
}
```

Example:

```json
"2026-09-23"
```

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "lancamento": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    },
    "periodo": {
      "type": "object",
      "properties": {
        "from": {
          "type": "string",
          "description": "Início."
        },
        "to": {
          "type": "string",
          "description": "Fim."
        },
        "dias": {
          "type": "integer",
          "description": "Dias."
        }
      },
      "required": [
        "from",
        "to",
        "dias"
      ]
    },
    "fontes": {
      "type": "object",
      "properties": {},
      "additionalProperties": {
        "type": "string",
        "description": "ok, erro ou nao_configurado."
      }
    },
    "totais": {
      "anyOf": [
        {
          "type": "object",
          "properties": {},
          "additionalProperties": true,
          "description": "Vendas, bruto por moeda, iniciados, falhos, pendentes, aprovação e conversão."
        },
        {
          "type": "null"
        }
      ]
    },
    "grupos": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "chave": {
            "type": "string",
            "description": "Grupo."
          }
        },
        "required": [
          "chave"
        ],
        "additionalProperties": true
      },
      "description": "Números por grupo de produto."
    },
    "serie": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "dia": {
            "type": "string",
            "description": "Dia."
          }
        },
        "required": [
          "dia"
        ],
        "additionalProperties": true
      },
      "description": "Série diária."
    },
    "pendencias": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {},
        "additionalProperties": true
      },
      "description": "Métricas sem fonte ligada."
    },
    "avisos": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "Aviso."
      },
      "description": "Lacunas e regras aplicadas."
    }
  },
  "required": [
    "lancamento",
    "periodo",
    "fontes",
    "grupos",
    "serie",
    "avisos"
  ]
}
```

Example:

```json
{
  "lancamento": {},
  "periodo": {
    "from": "string",
    "to": "string",
    "dias": 1
  },
  "fontes": {},
  "totais": {},
  "grupos": [
    {
      "chave": "string"
    }
  ],
  "serie": [
    {
      "dia": "string"
    }
  ],
  "pendencias": [
    {}
  ],
  "avisos": [
    "string"
  ]
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 404

Recurso não encontrado.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "recurso não encontrado"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### GET /api/lancamentos/{projetoId}/saude

Consultar a saúde de um lançamento

Aba Saúde: última venda, vendas e receita de hoje e o estado de cada fonte e rotina (leituras de pagamento, sincronização da linha do tempo, última recuperação enviada, último aviso do checkout e dados de anúncio). Exige a capability `vendas`.

- operationId: `getLaunchHealth`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `vendas`

#### Parameters

##### path projetoId

- required: true
- description: ID do projeto em hermes_projects.

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"string"
```

##### query aba

- required: false
- description: Aba do lançamento.

Schema:

```json
{
  "type": "string",
  "description": "Chave da aba."
}
```

Example:

```json
"lancamento"
```

##### query from

- required: false
- description: Início do período.

Schema:

```json
{
  "type": "string",
  "description": "Primeiro dia (YYYY-MM-DD).",
  "format": "date"
}
```

Example:

```json
"2026-09-21"
```

##### query to

- required: false
- description: Fim do período.

Schema:

```json
{
  "type": "string",
  "description": "Último dia (YYYY-MM-DD).",
  "format": "date"
}
```

Example:

```json
"2026-09-23"
```

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "description": "ok, sem_config ou nao_configurado."
    }
  },
  "required": [
    "status"
  ],
  "additionalProperties": true
}
```

Example:

```json
{
  "status": "processing"
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 404

Recurso não encontrado.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "recurso não encontrado"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### POST /api/mcp

Chamar o MCP Streamable HTTP do Hermes

Endpoint MCP oficial e stateless. Registra somente tools explícitas e encaminha cada ação para uma rota Hermes fixa com as mesmas guardas de capability, CAS e idempotência.

Envie mensagens JSON-RPC 2.0 do MCP por HTTP. Cada chamada é stateless, aceita sessão Supabase ou token pessoal `hms_live_` e só expõe ferramentas explícitas com as mesmas autorizações da API REST.

- operationId: `callHermesMcp`
- authentication: Supabase session or `hms_live_` personal bearer token

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

- required: true
- description: Mensagem JSON-RPC do protocolo MCP.

##### application/json

Schema:

```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": true
}
```

Example:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}
```

#### Responses

##### 200

Resposta MCP JSON-RPC.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": true
}
```

Example:

```json
{}
```

##### 202

Notificação MCP aceita sem resposta de ferramenta.

Schema: no response body.

Example: no response body.

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 405

Método MCP não suportado.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "string",
  "code": "string",
  "details": {}
}
```

##### 415

Content-Type precisa ser application/json.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "string",
  "code": "string",
  "details": {}
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### GET /api/me

Consultar membro autenticado e capacidades

Primeira chamada recomendada após autenticar. Em uma sessão Supabase, as capabilities vêm exclusivamente do cargo `access_level` do Studio; em um token pessoal, vêm da interseção entre scopes, nível individual da API e teto do cargo.

- operationId: `getCurrentMember`
- authentication: Supabase session or `hms_live_` personal bearer token

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "member": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "ID do membro."
        },
        "user_id": {
          "type": "string",
          "description": "ID do usuário Supabase vinculado."
        },
        "name": {
          "type": "string",
          "description": "Nome."
        },
        "email": {
          "anyOf": [
            {
              "type": "string",
              "description": "E-mail do membro.",
              "format": "email"
            },
            {
              "type": "null"
            }
          ]
        },
        "access_level": {
          "type": "string",
          "description": "Nível desta credencial: cargo do Studio para session; nível PAT efetivo para api_token.",
          "enum": [
            "nenhum",
            "leitor",
            "criador",
            "lider",
            "admin"
          ]
        },
        "team_access_level": {
          "type": "string",
          "description": "Cargo atual no Studio; governa a sessão e serve de teto somente para PAT.",
          "enum": [
            "criador",
            "lider",
            "admin"
          ]
        },
        "api_access_level": {
          "type": "string",
          "description": "Configuração de PAT na sessão; nível PAT efetivo quando auth.kind é api_token.",
          "enum": [
            "nenhum",
            "leitor",
            "criador",
            "lider",
            "admin"
          ]
        }
      },
      "required": [
        "id",
        "name",
        "access_level",
        "team_access_level",
        "api_access_level"
      ],
      "description": "Identidade e autorização da credencial atual: cargo do Studio para sessão ou nível efetivo para PAT."
    },
    "caps": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "Capability liberada."
      }
    },
    "auth": {
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "description": "Método que autenticou a chamada.",
          "enum": [
            "session",
            "api_token"
          ]
        },
        "token_id": {
          "anyOf": [
            {
              "type": "string",
              "description": "ID do token pessoal quando kind é api_token."
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "kind",
        "token_id"
      ],
      "description": "Método efetivamente usado para autenticar a requisição atual."
    }
  },
  "required": [
    "member",
    "caps",
    "auth"
  ]
}
```

Example:

```json
{
  "member": {
    "id": "id-exemplo",
    "user_id": "user-id-exemplo",
    "name": "Exemplo Hermes",
    "email": "membro@example.com",
    "access_level": "nenhum",
    "team_access_level": "criador",
    "api_access_level": "nenhum"
  },
  "caps": [
    "string"
  ],
  "auth": {
    "kind": "session",
    "token_id": "token-id-exemplo"
  }
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### GET /api/membros

Listar membros ativos

Lista membros ativos que podem receber atribuições, sem retornar credenciais ou registros já desativados.

- operationId: `listMembers`
- authentication: Supabase session bearer token (session only)
- required capability: `members`

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "membros": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "ID."
          },
          "name": {
            "type": "string",
            "description": "Nome."
          },
          "email": {
            "type": "string",
            "description": "E-mail.",
            "format": "email"
          },
          "role": {
            "anyOf": [
              {
                "type": "string",
                "description": "Função."
              },
              {
                "type": "null"
              }
            ]
          },
          "access_level": {
            "type": "string",
            "description": "Cargo no Studio.",
            "enum": [
              "criador",
              "lider",
              "admin"
            ]
          },
          "api_access_level": {
            "type": "string",
            "description": "Nível individual configurável somente para tokens pessoais da API; não limita sessões do Studio.",
            "enum": [
              "nenhum",
              "leitor",
              "criador",
              "lider",
              "admin"
            ]
          },
          "is_admin": {
            "type": "boolean",
            "description": "Compatibilidade com legado."
          },
          "financeiro": {
            "type": "boolean",
            "description": "Permissão por pessoa: vê o painel de Vendas (capability `vendas`)."
          }
        },
        "required": [
          "id",
          "name",
          "email",
          "access_level"
        ],
        "description": "Membro ativo que pode receber atribuições e capabilities."
      }
    }
  },
  "required": [
    "membros"
  ]
}
```

Example:

```json
{
  "membros": [
    {
      "id": "id-exemplo",
      "name": "Exemplo Hermes",
      "email": "membro@example.com",
      "role": "string",
      "access_level": "criador",
      "api_access_level": "nenhum",
      "is_admin": true,
      "financeiro": true
    }
  ]
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### PATCH /api/membros

Alterar nível de acesso ou permissão financeira

Altera o nível de acesso (criador, líder, admin) e/ou a permissão por pessoa `financeiro`, que libera o painel de Vendas. Informe ao menos um dos dois; as capabilities efetivas são recalculadas na próxima requisição. Evite elevar privilégios sem necessidade operacional.

- operationId: `updateMemberAccess`
- authentication: Supabase session bearer token (session only)
- required capability: `members`

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

- required: true
- description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema.

##### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "member_id": {
      "type": "string",
      "description": "Membro."
    },
    "access_level": {
      "type": "string",
      "description": "Nível.",
      "enum": [
        "criador",
        "lider",
        "admin"
      ]
    },
    "financeiro": {
      "type": "boolean",
      "description": "Liga ou desliga o acesso ao painel de Vendas."
    }
  },
  "required": [
    "member_id"
  ]
}
```

Example:

```json
{
  "member_id": "member-id",
  "access_level": "lider",
  "financeiro": false
}
```

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Sucesso."
    },
    "member_id": {
      "type": "string",
      "description": "Membro."
    },
    "access_level": {
      "type": "string",
      "description": "Nível resultante."
    },
    "financeiro": {
      "type": "boolean",
      "description": "Permissão financeira resultante."
    }
  },
  "required": [
    "ok",
    "member_id",
    "access_level",
    "financeiro"
  ]
}
```

Example:

```json
{
  "ok": true,
  "member_id": "member-id-exemplo",
  "access_level": "string",
  "financeiro": true
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 404

Recurso não encontrado.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "recurso não encontrado"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### POST /api/membros

Convidar um novo membro

O Supabase envia um link de convite para o e-mail informado. O usuário define a própria senha no fluxo de onboarding; a API nunca cria nem retorna senha provisória.

Envia um convite seguro por e-mail e cria o vínculo ativo na equipe. Nenhuma senha provisória é criada ou devolvida pela API.

- operationId: `createMember`
- authentication: Supabase session bearer token (session only)
- required capability: `members`

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

- required: true
- description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema.

##### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Nome."
    },
    "email": {
      "type": "string",
      "description": "E-mail.",
      "format": "email"
    },
    "access_level": {
      "type": "string",
      "description": "Nível.",
      "enum": [
        "criador",
        "lider",
        "admin"
      ]
    },
    "role": {
      "type": "string",
      "description": "Função livre."
    }
  },
  "required": [
    "name",
    "email",
    "access_level"
  ]
}
```

Example:

```json
{
  "name": "Novo membro",
  "email": "membro@example.com",
  "access_level": "criador"
}
```

#### Responses

##### 201

Convite enviado e membro criado.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Sucesso."
    },
    "member": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "ID."
        },
        "name": {
          "type": "string",
          "description": "Nome."
        },
        "email": {
          "type": "string",
          "description": "E-mail.",
          "format": "email"
        },
        "role": {
          "anyOf": [
            {
              "type": "string",
              "description": "Função."
            },
            {
              "type": "null"
            }
          ]
        },
        "access_level": {
          "type": "string",
          "description": "Cargo no Studio.",
          "enum": [
            "criador",
            "lider",
            "admin"
          ]
        },
        "api_access_level": {
          "type": "string",
          "description": "Nível individual configurável somente para tokens pessoais da API; não limita sessões do Studio.",
          "enum": [
            "nenhum",
            "leitor",
            "criador",
            "lider",
            "admin"
          ]
        },
        "is_admin": {
          "type": "boolean",
          "description": "Compatibilidade com legado."
        },
        "financeiro": {
          "type": "boolean",
          "description": "Permissão por pessoa: vê o painel de Vendas (capability `vendas`)."
        }
      },
      "required": [
        "id",
        "name",
        "email",
        "access_level"
      ],
      "description": "Membro ativo que pode receber atribuições e capabilities."
    },
    "invitation": {
      "type": "object",
      "properties": {
        "sent": {
          "type": "boolean",
          "description": "Confirma o envio do convite."
        },
        "email": {
          "type": "string",
          "description": "Destino normalizado.",
          "format": "email"
        }
      },
      "required": [
        "sent",
        "email"
      ]
    }
  },
  "required": [
    "ok",
    "member",
    "invitation"
  ]
}
```

Example:

```json
{
  "ok": true,
  "member": {
    "id": "member-id",
    "name": "Novo membro",
    "email": "membro@example.com",
    "access_level": "criador"
  },
  "invitation": {
    "sent": true,
    "email": "membro@example.com"
  }
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### DELETE /api/membros/{memberId}

Revogar acesso e limpar atribuições atuais

Não exclui tarefas, conteúdos nem histórico. Preserva o usuário e o membro como âncoras de autoria/FKs; pode retornar 207 quando o acesso foi revogado, mas alguma limpeza precisa ser repetida.

Revoga o login e remove apenas atribuições atuais. Conteúdos, tarefas e histórico permanecem preservados como registros de autoria.

- operationId: `deactivateMember`
- authentication: Supabase session bearer token (session only)
- required capability: `members`

#### Parameters

##### path memberId

- required: true
- description: ID de team_members.

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"string"
```

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Todas as limpezas terminaram."
    },
    "accessRevoked": {
      "type": "boolean",
      "description": "Acesso revogado."
    },
    "alreadyInactive": {
      "type": "boolean",
      "description": "Já estava inativo."
    },
    "retryable": {
      "type": "boolean",
      "description": "Uma repetição é segura."
    },
    "member": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "ID."
        },
        "name": {
          "type": "string",
          "description": "Nome."
        },
        "email": {
          "type": "string",
          "description": "E-mail.",
          "format": "email"
        }
      },
      "required": [
        "id",
        "name",
        "email"
      ]
    },
    "summary": {
      "type": "object",
      "properties": {
        "events": {
          "type": "integer",
          "description": "Eventos alterados."
        },
        "tasks": {
          "type": "integer",
          "description": "Tarefas desatribuídas."
        },
        "comments": {
          "type": "integer",
          "description": "Comentários alterados."
        },
        "platforms": {
          "type": "integer",
          "description": "Plataformas alteradas."
        },
        "projects": {
          "type": "integer",
          "description": "Projetos alterados."
        },
        "authBan": {
          "type": "object",
          "properties": {},
          "additionalProperties": true
        }
      },
      "required": [
        "events",
        "tasks",
        "comments",
        "platforms",
        "projects",
        "authBan"
      ]
    },
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "scope": {
            "type": "string",
            "description": "Escopo."
          },
          "error": {
            "type": "string",
            "description": "Erro."
          }
        },
        "required": [
          "scope",
          "error"
        ]
      }
    }
  },
  "required": [
    "ok",
    "accessRevoked",
    "alreadyInactive",
    "retryable",
    "member",
    "summary",
    "errors"
  ],
  "description": "Relatório do desligamento seguro e das limpezas de atribuição."
}
```

Example:

```json
{
  "ok": true,
  "accessRevoked": true,
  "alreadyInactive": true,
  "retryable": true,
  "member": {
    "id": "id-exemplo",
    "name": "Exemplo Hermes",
    "email": "membro@example.com"
  },
  "summary": {
    "events": 1,
    "tasks": 1,
    "comments": 1,
    "platforms": 1,
    "projects": 1,
    "authBan": {}
  },
  "errors": [
    {
      "scope": "string",
      "error": "string"
    }
  ]
}
```

##### 207

Acesso revogado; uma ou mais limpezas falharam e são repetíveis.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Todas as limpezas terminaram."
    },
    "accessRevoked": {
      "type": "boolean",
      "description": "Acesso revogado."
    },
    "alreadyInactive": {
      "type": "boolean",
      "description": "Já estava inativo."
    },
    "retryable": {
      "type": "boolean",
      "description": "Uma repetição é segura."
    },
    "member": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "ID."
        },
        "name": {
          "type": "string",
          "description": "Nome."
        },
        "email": {
          "type": "string",
          "description": "E-mail.",
          "format": "email"
        }
      },
      "required": [
        "id",
        "name",
        "email"
      ]
    },
    "summary": {
      "type": "object",
      "properties": {
        "events": {
          "type": "integer",
          "description": "Eventos alterados."
        },
        "tasks": {
          "type": "integer",
          "description": "Tarefas desatribuídas."
        },
        "comments": {
          "type": "integer",
          "description": "Comentários alterados."
        },
        "platforms": {
          "type": "integer",
          "description": "Plataformas alteradas."
        },
        "projects": {
          "type": "integer",
          "description": "Projetos alterados."
        },
        "authBan": {
          "type": "object",
          "properties": {},
          "additionalProperties": true
        }
      },
      "required": [
        "events",
        "tasks",
        "comments",
        "platforms",
        "projects",
        "authBan"
      ]
    },
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "scope": {
            "type": "string",
            "description": "Escopo."
          },
          "error": {
            "type": "string",
            "description": "Erro."
          }
        },
        "required": [
          "scope",
          "error"
        ]
      }
    }
  },
  "required": [
    "ok",
    "accessRevoked",
    "alreadyInactive",
    "retryable",
    "member",
    "summary",
    "errors"
  ],
  "description": "Relatório do desligamento seguro e das limpezas de atribuição."
}
```

Example:

```json
{
  "ok": true,
  "accessRevoked": true,
  "alreadyInactive": true,
  "retryable": true,
  "member": {
    "id": "id-exemplo",
    "name": "Exemplo Hermes",
    "email": "membro@example.com"
  },
  "summary": {
    "events": 1,
    "tasks": 1,
    "comments": 1,
    "platforms": 1,
    "projects": 1,
    "authBan": {}
  },
  "errors": [
    {
      "scope": "string",
      "error": "string"
    }
  ]
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 404

Recurso não encontrado.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "recurso não encontrado"
}
```

##### 409

Operação conflita com o estado atual.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "conflito"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### POST /api/membros/{memberId}/senha

Definir senha nova para um membro

Para quem perdeu a senha e não consegue usar o e-mail de recuperação. A senha é escolhida pelo administrador, aplicada pelo Auth Admin e nunca é armazenada, logada ou devolvida. Não se aplica à própria conta (409).

- operationId: `setMemberPassword`
- authentication: Supabase session bearer token (session only)
- required capability: `members`

#### Parameters

##### path memberId

- required: true
- description: ID de team_members.

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"string"
```

#### Request body

- required: true
- description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema.

##### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "password": {
      "type": "string",
      "description": "Senha nova (8 a 72 caracteres).",
      "minLength": 8,
      "maxLength": 72,
      "format": "password"
    }
  },
  "required": [
    "password"
  ]
}
```

Example:

```json
{
  "password": "********"
}
```

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Sucesso."
    },
    "member": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "ID do membro."
        },
        "name": {
          "type": "string",
          "description": "Nome."
        },
        "email": {
          "anyOf": [
            {
              "type": "string",
              "description": "E-mail.",
              "format": "email"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "id",
        "name"
      ]
    }
  },
  "required": [
    "ok",
    "member"
  ]
}
```

Example:

```json
{
  "ok": true,
  "member": {
    "id": "id-exemplo",
    "name": "Exemplo Hermes",
    "email": "membro@example.com"
  }
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 404

Recurso não encontrado.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "recurso não encontrado"
}
```

##### 409

Operação conflita com o estado atual.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "conflito"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### POST /api/orbum/cancelamentos

Registrar o motivo de saída de um assinante do Orbum

Grava em `orbum_cancelamentos` o motivo, a oferta feita e o resultado (skill resgate-cancelamento-orbum). Não aceita dado pessoal: a pessoa é o hash vindo de /api/orbum/saidas.

- operationId: `createOrbumCancelReason`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `vendas`

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

- required: true
- description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema.

##### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "pessoa": {
      "type": "string",
      "description": "Hash do e-mail (24 hex)."
    },
    "motivo": {
      "type": "string",
      "description": "Motivo.",
      "enum": [
        "financeiro",
        "tempo",
        "ja_vi",
        "insatisfacao",
        "reembolso",
        "tecnico",
        "outro"
      ]
    },
    "oferta": {
      "anyOf": [
        {
          "type": "string",
          "description": "Oferta feita.",
          "enum": [
            "nenhuma",
            "desconto",
            "congelamento",
            "troca_plano",
            "outra"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "resultado": {
      "anyOf": [
        {
          "type": "string",
          "description": "Resultado.",
          "enum": [
            "saiu",
            "ficou",
            "congelou",
            "pendente"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "observacao": {
      "anyOf": [
        {
          "type": "string",
          "description": "Até 500 caracteres, sem dados pessoais."
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "pessoa",
    "motivo"
  ]
}
```

Example:

```json
{
  "pessoa": "string",
  "motivo": "financeiro",
  "oferta": "nenhuma",
  "resultado": "saiu",
  "observacao": "string"
}
```

#### Responses

##### 201

Motivo registrado.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Gravado."
    },
    "id": {
      "type": "integer",
      "description": "Id do registro."
    },
    "registrado_em": {
      "type": "string",
      "description": "Instante.",
      "format": "date-time"
    }
  },
  "required": [
    "ok"
  ]
}
```

Example:

```json
{
  "ok": true,
  "id": 1,
  "registrado_em": "2026-08-22T15:00:00.000Z"
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### GET /api/orbum/resumo

Consultar o painel da assinatura Orbum

Cruza o acesso no TheMembers com o pagamento (Hotmart, Pagar.me, Asaas) pessoa a pessoa. Assinante ativo é quem tem pagamento vigente; acesso sem pagamento, pagamento sem acesso e atraso vêm em `alertas`. Grava uma foto agregada por dia em `orbum_snapshots` e devolve o histórico. Só agregados. `atualizar=1` ignora o cache de 10 minutos.

- operationId: `getOrbumSummary`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `vendas`

#### Parameters

##### query atualizar

- required: false
- description: Força uma leitura nova das fontes.

Schema:

```json
{
  "type": "string",
  "description": "`1` para ignorar o cache.",
  "enum": [
    "1"
  ]
}
```

Example:

```json
"1"
```

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Painel do Orbum.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "kpis": {
      "type": "object",
      "properties": {},
      "additionalProperties": true,
      "description": "pagantes, com_acesso, receita_recorrente_mensal, ticket_mensal, entradas_mes, saidas_mes, churn_mes, saida_anunciada, sem_renovacao_prevista."
    },
    "alertas": {
      "type": "object",
      "properties": {},
      "additionalProperties": true,
      "description": "pagando_sem_acesso, acesso_sem_pagamento (pagou_antes, nunca_pagou), atraso_com_acesso, atraso_sem_acesso, sem_renovacao_prevista."
    },
    "por_plano": {
      "type": "object",
      "properties": {},
      "additionalProperties": true,
      "description": "Pagantes por plano."
    },
    "por_renovacao": {
      "type": "object",
      "properties": {},
      "additionalProperties": true,
      "description": "Pagantes por tipo de renovação: automatica, manual, cancelada."
    },
    "por_fonte": {
      "type": "object",
      "properties": {},
      "additionalProperties": true,
      "description": "Pagantes por gateway."
    },
    "vencimentos": {
      "type": "object",
      "properties": {},
      "additionalProperties": true,
      "description": "Fim do período pago em 30, 60 e 90 dias, por tipo de renovação."
    },
    "serie": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "mes": {
            "type": "string",
            "description": "Mês YYYY-MM."
          }
        },
        "required": [
          "mes"
        ],
        "additionalProperties": true
      },
      "description": "Últimos 12 meses pelo acesso: ativos no fim do mês, entradas, saídas e churn."
    },
    "receita": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "mes": {
            "type": "string",
            "description": "Mês YYYY-MM."
          }
        },
        "required": [
          "mes"
        ],
        "additionalProperties": true
      },
      "description": "Receita por mês: novas e renovações, em reais."
    },
    "historico": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "dia": {
            "type": "string",
            "description": "Dia YYYY-MM-DD."
          }
        },
        "required": [
          "dia"
        ],
        "additionalProperties": true
      },
      "description": "Foto diária gravada pelo painel: pagantes, com acesso e receita recorrente."
    },
    "atualizado_em": {
      "type": "object",
      "properties": {},
      "additionalProperties": true,
      "description": "Último sync de cada fonte."
    },
    "avisos": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "Aviso operacional."
      },
      "description": "Lacunas e fallbacks aplicados."
    }
  },
  "required": [
    "kpis",
    "alertas",
    "serie",
    "receita",
    "avisos"
  ]
}
```

Example:

```json
{
  "kpis": {},
  "alertas": {},
  "por_plano": {},
  "por_renovacao": {},
  "por_fonte": {},
  "vencimentos": {},
  "serie": [
    {
      "mes": "string"
    }
  ],
  "receita": [
    {
      "mes": "string"
    }
  ],
  "historico": [
    {
      "dia": "string"
    }
  ],
  "atualizado_em": {},
  "avisos": [
    "string"
  ]
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

##### 503

Recurso não configurado neste servidor.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "painel de vendas não configurado neste servidor",
  "code": "VENDAS_NOT_CONFIGURED"
}
```

### GET /api/orbum/saidas

Listar quem está saindo do Orbum

Pessoas que vão sair (acesso valendo sem cobrança futura), estão em atraso ou saíram nos últimos 60 dias, com e-mail mascarado e o motivo já registrado. `pessoa` é o hash do e-mail usado no registro do motivo.

- operationId: `listOrbumExits`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `vendas`

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Saídas do Orbum.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "saidas": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "pessoa": {
            "type": "string",
            "description": "Hash do e-mail."
          },
          "grupo": {
            "type": "string",
            "description": "vai_sair, atraso ou saiu."
          }
        },
        "required": [
          "pessoa",
          "grupo"
        ],
        "additionalProperties": true
      },
      "description": "Lista ordenada por grupo e data."
    },
    "motivos_registrados": {
      "type": "object",
      "properties": {},
      "additionalProperties": true,
      "description": "Contagem por motivo."
    },
    "total_registros": {
      "type": "integer",
      "description": "Registros de motivo."
    }
  },
  "required": [
    "saidas"
  ]
}
```

Example:

```json
{
  "saidas": [
    {
      "pessoa": "string",
      "grupo": "string"
    }
  ],
  "motivos_registrados": {},
  "total_registros": 1
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

##### 503

Recurso não configurado neste servidor.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "painel de vendas não configurado neste servidor",
  "code": "VENDAS_NOT_CONFIGURED"
}
```

### GET /api/plataformas/{platformId}/senha

Ler a senha de uma plataforma

Exige sessão Supabase de administrador da equipe e nunca aceita token pessoal nem MCP. Decifra e devolve a senha de uma única plataforma de Gastos de Aplicativos; o banco guarda só a cifra. A auditoria da API registra quem pediu, qual plataforma e quando, sem o valor.

- operationId: `getPlatformPassword`
- authentication: Supabase session bearer token (session only)
- required capability: `team_admin`

#### Parameters

##### path platformId

- required: true
- description: ID (UUID) da plataforma em Gastos de Aplicativos.

Schema:

```json
{
  "type": "string",
  "format": "uuid"
}
```

Example:

```json
"00000000-0000-4000-8000-000000000000"
```

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "senha": {
      "anyOf": [
        {
          "type": "string",
          "description": "Senha decifrada; null quando não há senha salva.",
          "format": "password"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "senha"
  ]
}
```

Example:

```json
{
  "senha": "********"
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 404

Recurso não encontrado.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "recurso não encontrado"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### PUT /api/plataformas/{platformId}/senha

Gravar ou apagar a senha de uma plataforma

Exige sessão Supabase de administrador da equipe. Cifra e grava a senha de uma plataforma (AES-256-GCM no servidor) ou apaga a senha salva com `senha: null`. A resposta nunca devolve o valor.

- operationId: `setPlatformPassword`
- authentication: Supabase session bearer token (session only)
- required capability: `team_admin`

#### Parameters

##### path platformId

- required: true
- description: ID (UUID) da plataforma em Gastos de Aplicativos.

Schema:

```json
{
  "type": "string",
  "format": "uuid"
}
```

Example:

```json
"00000000-0000-4000-8000-000000000000"
```

#### Request body

- required: true
- description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema.

##### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "senha": {
      "anyOf": [
        {
          "type": "string",
          "description": "Senha nova (até 500 caracteres); null ou vazio apaga a senha salva.",
          "maxLength": 500,
          "format": "password"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "senha"
  ]
}
```

Example:

```json
{
  "senha": "********"
}
```

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Sucesso."
    },
    "has_password": {
      "type": "boolean",
      "description": "Se a plataforma ficou com senha salva."
    }
  },
  "required": [
    "ok",
    "has_password"
  ]
}
```

Example:

```json
{
  "ok": true,
  "has_password": true
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 404

Recurso não encontrado.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "recurso não encontrado"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### GET /api/projects

Listar projetos colaborativos

Paginação determinística por created_at. Use created_after com o último timestamp recebido.

Lista projetos em ordem determinística de criação. Para paginação, use o `created_at` do último item como cursor exclusivo em `created_after`.

- operationId: `listProjects`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `projects_view`

#### Parameters

##### query created_after

- required: false
- description: Cursor exclusivo de criação.

Schema:

```json
{
  "type": "string",
  "format": "date-time"
}
```

Example:

```json
"2026-09-02T15:00:00.000Z"
```

##### query limit

- required: false
- description: Máximo de projetos.

Schema:

```json
{
  "type": "integer",
  "minimum": 1,
  "maximum": 200,
  "default": 100
}
```

Example:

```json
100
```

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "projects": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "ID do projeto."
          },
          "name": {
            "type": "string",
            "description": "Nome."
          },
          "payload": {
            "type": "object",
            "properties": {},
            "additionalProperties": true
          },
          "api_revision": {
            "type": "integer",
            "description": "Token CAS canônico.",
            "minimum": 0
          },
          "revision": {
            "type": "integer",
            "description": "Alias de api_revision.",
            "minimum": 0
          },
          "created_at": {
            "type": "string",
            "description": "Criação ISO.",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "description": "Atualização ISO.",
            "format": "date-time"
          },
          "created_by": {
            "type": "string",
            "description": "Usuário criador."
          },
          "updated_by": {
            "type": "string",
            "description": "Último usuário editor."
          }
        },
        "required": [
          "id",
          "name",
          "payload",
          "api_revision",
          "revision",
          "created_at",
          "updated_at",
          "created_by",
          "updated_by"
        ],
        "description": "Documento colaborativo de projeto e seus tokens de concorrência."
      }
    }
  },
  "required": [
    "projects"
  ]
}
```

Example:

```json
{
  "projects": [
    {
      "id": "id-exemplo",
      "name": "Exemplo Hermes",
      "payload": {},
      "api_revision": 0,
      "revision": 0,
      "created_at": "2026-08-22T15:00:00.000Z",
      "updated_at": "2026-08-22T15:00:00.000Z",
      "created_by": "string",
      "updated_by": "string"
    }
  ]
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### POST /api/projects

Criar projeto colaborativo vazio

Cria um documento de projeto vazio no formato atual. Forneça uma chave de idempotência para tornar retries de rede seguros.

- operationId: `createProject`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `projects_manage`

#### Parameters

##### header Idempotency-Key

- required: false
- description: Chave opcional de 8 a 128 caracteres seguros. Repita a mesma chave somente com o mesmo payload; reutilização com conteúdo diferente retorna 409.

Schema:

```json
{
  "type": "string",
  "minLength": 8,
  "maxLength": 128,
  "pattern": "^[A-Za-z0-9._:~-]+$"
}
```

Example:

```json
"docs-20260822-001"
```

#### Request body

- required: true
- description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema.

##### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Nome do projeto.",
      "minLength": 1,
      "maxLength": 200
    }
  },
  "required": [
    "name"
  ]
}
```

Example:

```json
{
  "name": "Lançamento Xamanismo"
}
```

#### Responses

##### 201

Projeto criado.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Sucesso."
    },
    "project": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "ID do projeto."
        },
        "name": {
          "type": "string",
          "description": "Nome."
        },
        "payload": {
          "type": "object",
          "properties": {},
          "additionalProperties": true
        },
        "api_revision": {
          "type": "integer",
          "description": "Token CAS canônico.",
          "minimum": 0
        },
        "revision": {
          "type": "integer",
          "description": "Alias de api_revision.",
          "minimum": 0
        },
        "created_at": {
          "type": "string",
          "description": "Criação ISO.",
          "format": "date-time"
        },
        "updated_at": {
          "type": "string",
          "description": "Atualização ISO.",
          "format": "date-time"
        },
        "created_by": {
          "type": "string",
          "description": "Usuário criador."
        },
        "updated_by": {
          "type": "string",
          "description": "Último usuário editor."
        }
      },
      "required": [
        "id",
        "name",
        "payload",
        "api_revision",
        "revision",
        "created_at",
        "updated_at",
        "created_by",
        "updated_by"
      ],
      "description": "Documento colaborativo de projeto e seus tokens de concorrência."
    }
  },
  "required": [
    "ok",
    "project"
  ]
}
```

Example:

```json
{
  "ok": true,
  "project": {
    "id": "id-exemplo",
    "name": "Exemplo Hermes",
    "payload": {},
    "api_revision": 0,
    "revision": 0,
    "created_at": "2026-08-22T15:00:00.000Z",
    "updated_at": "2026-08-22T15:00:00.000Z",
    "created_by": "string",
    "updated_by": "string"
  }
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 409

Operação conflita com o estado atual.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "conflito"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### GET /api/projects/{projectId}

Consultar um projeto e seu token CAS

Retorna o projeto completo e os tokens `api_revision`/`revision`. Sempre leia esta rota antes de aplicar uma alteração semântica.

- operationId: `getProject`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `projects_view`

#### Parameters

##### path projectId

- required: true
- description: ID de hermes_projects.

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"string"
```

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "project": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "ID do projeto."
        },
        "name": {
          "type": "string",
          "description": "Nome."
        },
        "payload": {
          "type": "object",
          "properties": {},
          "additionalProperties": true
        },
        "api_revision": {
          "type": "integer",
          "description": "Token CAS canônico.",
          "minimum": 0
        },
        "revision": {
          "type": "integer",
          "description": "Alias de api_revision.",
          "minimum": 0
        },
        "created_at": {
          "type": "string",
          "description": "Criação ISO.",
          "format": "date-time"
        },
        "updated_at": {
          "type": "string",
          "description": "Atualização ISO.",
          "format": "date-time"
        },
        "created_by": {
          "type": "string",
          "description": "Usuário criador."
        },
        "updated_by": {
          "type": "string",
          "description": "Último usuário editor."
        }
      },
      "required": [
        "id",
        "name",
        "payload",
        "api_revision",
        "revision",
        "created_at",
        "updated_at",
        "created_by",
        "updated_by"
      ],
      "description": "Documento colaborativo de projeto e seus tokens de concorrência."
    }
  },
  "required": [
    "project"
  ]
}
```

Example:

```json
{
  "project": {
    "id": "id-exemplo",
    "name": "Exemplo Hermes",
    "payload": {},
    "api_revision": 0,
    "revision": 0,
    "created_at": "2026-08-22T15:00:00.000Z",
    "updated_at": "2026-08-22T15:00:00.000Z",
    "created_by": "string",
    "updated_by": "string"
  }
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 404

Recurso não encontrado.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "recurso não encontrado"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### GET /api/projects/{projectId}/operations

Listar histórico de operações do projeto

Exibe o histórico imutável de operações semânticas, da revisão mais recente para a mais antiga, para auditoria e reconstrução de mudanças.

- operationId: `listProjectOperations`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `projects_audit_view`

#### Parameters

##### path projectId

- required: true
- description: ID de hermes_projects.

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"string"
```

##### query limit

- required: false
- description: Máximo de operações.

Schema:

```json
{
  "type": "integer",
  "minimum": 1,
  "maximum": 200,
  "default": 50
}
```

Example:

```json
50
```

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "operations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "ID da operação."
          },
          "payload_revision": {
            "type": "integer",
            "description": "Revisão produzida.",
            "minimum": 0
          },
          "operation_type": {
            "type": "string",
            "description": "Tipo."
          },
          "operation": {
            "type": "object",
            "properties": {},
            "additionalProperties": true
          },
          "actor_member_id": {
            "type": "string",
            "description": "Membro autor."
          },
          "actor_user_id": {
            "type": "string",
            "description": "Usuário autor."
          },
          "created_at": {
            "type": "string",
            "description": "Data ISO.",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "payload_revision",
          "operation_type",
          "operation",
          "created_at"
        ],
        "description": "Registro imutável de uma operação já aplicada ao projeto."
      }
    },
    "revision": {
      "type": "integer",
      "description": "api_revision atual.",
      "minimum": 0
    }
  },
  "required": [
    "operations",
    "revision"
  ]
}
```

Example:

```json
{
  "operations": [
    {
      "id": "id-exemplo",
      "payload_revision": 0,
      "operation_type": "string",
      "operation": {},
      "actor_member_id": "actor-member-id-exemplo",
      "actor_user_id": "actor-user-id-exemplo",
      "created_at": "2026-08-22T15:00:00.000Z"
    }
  ],
  "revision": 0
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 404

Recurso não encontrado.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "recurso não encontrado"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### POST /api/projects/{projectId}/operations

Aplicar uma operação semântica com CAS

Nunca envie um snapshot inteiro. Leia o projeto, use revision/api_revision como expected_revision e aplique uma operação. Em 409, releia antes de decidir um novo payload. O servidor exige `projects_manage` para estrutura, ordem e responsáveis. Com somente `projects_edit`, task.update exige atribuição na tarefa e subtask.update exige atribuição na subtarefa ou tarefa-pai; comentários próprios continuam permitidos.

Aplica uma única mudança semântica ao projeto. Criadores só atualizam tarefas atribuídas à própria conta; líderes e admins podem gerenciar a equipe. Nunca envie um snapshot inteiro e, em conflito `409`, releia o projeto.

- operationId: `applyProjectOperation`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `projects_edit`
- dynamic capability dispatch: `{"default":"projects_edit","projects_manage":["meta.update","goal.add","goal.update","goal.remove","goal.reorder","task.add","task.remove","task.reorder","task.assignees.set","subtask.add","subtask.remove","subtask.reorder","subtask.assignees.set"]}`

#### Parameters

##### header Idempotency-Key

- required: false
- description: Chave opcional de 8 a 128 caracteres seguros. Repita a mesma chave somente com o mesmo payload; reutilização com conteúdo diferente retorna 409.

Schema:

```json
{
  "type": "string",
  "minLength": 8,
  "maxLength": 128,
  "pattern": "^[A-Za-z0-9._:~-]+$"
}
```

Example:

```json
"docs-20260822-001"
```

##### path projectId

- required: true
- description: ID de hermes_projects.

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"string"
```

#### Request body

- required: true
- description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema.

##### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "expected_revision": {
      "type": "integer",
      "description": "api_revision da leitura mais recente.",
      "minimum": 0
    },
    "expected_updated_at": {
      "type": "string",
      "description": "Token timestamp adicional opcional.",
      "format": "date-time"
    },
    "operation": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "description": "Tipo semântico da operação.",
          "enum": [
            "meta.update",
            "goal.add",
            "goal.update",
            "goal.remove",
            "goal.reorder",
            "task.add",
            "task.update",
            "task.remove",
            "task.reorder",
            "task.assignees.set",
            "subtask.add",
            "subtask.update",
            "subtask.remove",
            "subtask.reorder",
            "subtask.assignees.set",
            "comment.add",
            "comment.update",
            "comment.remove"
          ]
        }
      },
      "required": [
        "type"
      ],
      "additionalProperties": true
    }
  },
  "required": [
    "expected_revision",
    "operation"
  ],
  "description": "Envelope de uma alteração semântica e atômica de projeto."
}
```

Example:

```json
{
  "expected_revision": 4,
  "expected_updated_at": "2026-08-21T12:00:00.000Z",
  "operation": {
    "type": "task.add",
    "title": "Revisar copy",
    "status": "pending"
  }
}
```

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Sucesso."
    },
    "project": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "ID do projeto."
        },
        "name": {
          "type": "string",
          "description": "Nome."
        },
        "payload": {
          "type": "object",
          "properties": {},
          "additionalProperties": true
        },
        "api_revision": {
          "type": "integer",
          "description": "Token CAS canônico.",
          "minimum": 0
        },
        "revision": {
          "type": "integer",
          "description": "Alias de api_revision.",
          "minimum": 0
        },
        "created_at": {
          "type": "string",
          "description": "Criação ISO.",
          "format": "date-time"
        },
        "updated_at": {
          "type": "string",
          "description": "Atualização ISO.",
          "format": "date-time"
        },
        "created_by": {
          "type": "string",
          "description": "Usuário criador."
        },
        "updated_by": {
          "type": "string",
          "description": "Último usuário editor."
        }
      },
      "required": [
        "id",
        "name",
        "payload",
        "api_revision",
        "revision",
        "created_at",
        "updated_at",
        "created_by",
        "updated_by"
      ],
      "description": "Documento colaborativo de projeto e seus tokens de concorrência."
    }
  },
  "required": [
    "ok",
    "project"
  ]
}
```

Example:

```json
{
  "ok": true,
  "project": {
    "id": "id-exemplo",
    "name": "Exemplo Hermes",
    "payload": {},
    "api_revision": 0,
    "revision": 0,
    "created_at": "2026-08-22T15:00:00.000Z",
    "updated_at": "2026-08-22T15:00:00.000Z",
    "created_by": "string",
    "updated_by": "string"
  }
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 404

Recurso não encontrado.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "recurso não encontrado"
}
```

##### 409

Operação conflita com o estado atual.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "conflito"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### POST /api/rag

Buscar contexto e citações no Cérebro

Pesquisa o Cérebro e devolve contexto consolidado, resultados e citações. Preserve as citações ao produzir conteúdo derivado.

- operationId: `searchHermesKnowledge`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `rag`

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

- required: true
- description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema.

##### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "tema": {
      "type": "string",
      "description": "Tema; `termo` é aceito como alias."
    },
    "termo": {
      "type": "string",
      "description": "Alias de tema."
    },
    "n_chunks": {
      "type": "integer",
      "description": "Quantidade de chunks de contexto.",
      "default": 6,
      "minimum": 1
    },
    "n_resultados": {
      "type": "integer",
      "description": "Quantidade de resultados.",
      "default": 4,
      "minimum": 1
    }
  }
}
```

Example:

```json
{
  "tema": "consciência",
  "n_chunks": 6,
  "n_resultados": 4
}
```

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "contexto": {
      "type": "string",
      "description": "Contexto consolidado."
    },
    "fontes": {
      "anyOf": [
        {},
        {
          "type": "null"
        }
      ]
    },
    "resultados": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "titulo": {
            "anyOf": [
              {
                "type": "string",
                "description": "Título."
              },
              {
                "type": "null"
              }
            ]
          },
          "fonte": {
            "anyOf": [
              {
                "type": "string",
                "description": "Fonte."
              },
              {
                "type": "null"
              }
            ]
          },
          "texto": {
            "type": "string",
            "description": "Trecho."
          },
          "citacao": {
            "type": "object",
            "properties": {
              "pagina": {
                "type": "integer",
                "description": "Página detectada."
              }
            },
            "additionalProperties": false
          }
        },
        "required": [
          "texto",
          "citacao"
        ]
      }
    }
  },
  "required": [
    "contexto",
    "resultados"
  ],
  "description": "Contexto e evidências retornados pela pesquisa no Cérebro."
}
```

Example:

```json
{
  "contexto": "Conteúdo de exemplo",
  "fontes": "string",
  "resultados": [
    {
      "titulo": "Conteúdo editorial",
      "fonte": "string",
      "texto": "Conteúdo de exemplo",
      "citacao": {
        "pagina": 1
      }
    }
  ]
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### POST /api/reels

Iniciar geração assíncrona de vídeo

Cria um job assíncrono de vídeo e retorna imediatamente o identificador para polling. Somente o criador do job ou líderes podem consultar o resultado.

- operationId: `generateReel`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `video`

#### Parameters

##### header Idempotency-Key

- required: false
- description: Chave opcional de 8 a 128 caracteres seguros. Repita a mesma chave somente com o mesmo payload; reutilização com conteúdo diferente retorna 409.

Schema:

```json
{
  "type": "string",
  "minLength": 8,
  "maxLength": 128,
  "pattern": "^[A-Za-z0-9._:~-]+$"
}
```

Example:

```json
"docs-20260822-001"
```

#### Request body

- required: true
- description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema.

##### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "event_id": {
      "type": "string",
      "description": "Evento opcional."
    },
    "prompt": {
      "type": "string",
      "description": "Cena base."
    },
    "motion": {
      "type": "string",
      "description": "Movimento desejado."
    },
    "duration": {
      "type": "string",
      "description": "Duração em segundos.",
      "default": "6"
    },
    "resolution": {
      "type": "string",
      "description": "Resolução.",
      "default": "720p"
    }
  },
  "required": [
    "prompt"
  ]
}
```

Example:

```json
{
  "prompt": "Luzes sutis na floresta",
  "duration": "6",
  "resolution": "720p"
}
```

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string",
      "description": "ID do job."
    },
    "state": {
      "type": "string",
      "description": "Estado.",
      "const": "processing"
    },
    "aviso": {
      "type": "string",
      "description": "Orientação de polling."
    }
  },
  "required": [
    "job_id",
    "state",
    "aviso"
  ],
  "description": "Confirmação de que a geração assíncrona de vídeo entrou na fila."
}
```

Example:

```json
{
  "job_id": "job-id-exemplo",
  "state": "processing",
  "aviso": "string"
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 404

Recurso não encontrado.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "recurso não encontrado"
}
```

##### 409

Operação conflita com o estado atual.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "conflito"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### GET /api/reels/{id}

Consultar uma geração de vídeo

Consulta o estado de um job de vídeo. Faça polling moderado até `completed` ou `failed`; a URL só está disponível após conclusão.

- operationId: `getReelJob`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `reels_view`

#### Parameters

##### path id

- required: true
- description: ID da geração de Reel.

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"string"
```

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "state": {
      "type": "string",
      "description": "Estado."
    },
    "error": {
      "anyOf": [
        {
          "type": "string",
          "description": "Erro do worker."
        },
        {
          "type": "null"
        }
      ]
    },
    "url": {
      "type": "string",
      "description": "URL quando concluído.",
      "format": "uri"
    }
  },
  "required": [
    "state"
  ],
  "description": "Estado observável de uma geração de vídeo."
}
```

Example:

```json
{
  "state": "processing",
  "error": "string",
  "url": "https://socialmedia.janvalellam.com.br/media/media-id?exp=1790000000&sig=assinatura"
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 404

Recurso não encontrado.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "recurso não encontrado"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### POST /api/roteiro

Gerar roteiro com pesquisa e verificação

Gera um roteiro a partir do tema usando a camada de inteligência do Hermes. O formato detalhado pode evoluir e campos adicionais devem ser preservados pelos clientes.

- operationId: `generateScript`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `roteiro`

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

- required: true
- description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema.

##### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "tema": {
      "type": "string",
      "description": "Tema do roteiro."
    }
  },
  "required": [
    "tema"
  ]
}
```

Example:

```json
{
  "tema": "O poder da curiosidade"
}
```

#### Responses

##### 200

Roteiro gerado pela camada de inteligência.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": true
}
```

Example:

```json
{}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### GET /api/skills

Listar skills publicadas

Lista as skills versionadas publicadas no backend, com filtro opcional pelo nome estável.

- operationId: `listSkills`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `skills_view`

#### Parameters

##### query name

- required: false
- description: Filtrar pelo nome exato.

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"string"
```

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "skills": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Nome."
          },
          "content": {
            "type": "string",
            "description": "Conteúdo."
          },
          "version": {
            "type": "integer",
            "description": "Versão."
          },
          "updated_at": {
            "anyOf": [
              {
                "type": "string",
                "description": "Atualização ISO.",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "name",
          "content",
          "version"
        ],
        "description": "Conteúdo versionado de uma skill publicada no backend."
      }
    }
  },
  "required": [
    "skills"
  ]
}
```

Example:

```json
{
  "skills": [
    {
      "name": "Exemplo Hermes",
      "content": "Conteúdo de exemplo",
      "version": 1,
      "updated_at": "2026-08-22T15:00:00.000Z"
    }
  ]
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### POST /api/skills

Publicar nova versão de uma skill

Publica uma nova versão do conteúdo de uma skill. Não sobrescreve silenciosamente o histórico e exige a capability `config`.

- operationId: `publishSkill`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `config`

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

- required: true
- description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema.

##### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Nome estável."
    },
    "content": {
      "type": "string",
      "description": "Conteúdo integral da skill."
    }
  },
  "required": [
    "name",
    "content"
  ]
}
```

Example:

```json
{
  "name": "hermes-calendar",
  "content": "# Hermes Calendar"
}
```

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Sucesso."
    },
    "name": {
      "type": "string",
      "description": "Nome."
    },
    "version": {
      "type": "integer",
      "description": "Nova versão."
    }
  },
  "required": [
    "ok",
    "name",
    "version"
  ]
}
```

Example:

```json
{
  "ok": true,
  "name": "Exemplo Hermes",
  "version": 1
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### GET /api/tarefas

Listar tarefas ativas do membro

Lista tarefas ativas visíveis ao membro autenticado. Cada evento inclui `api_revision`, que deve ser reutilizado em mutações protegidas por CAS.

- operationId: `listMyTasks`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `tasks_view`

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "tarefas": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Identificador do evento."
          },
          "api_revision": {
            "type": "integer",
            "description": "Token CAS da API; releia o evento antes de toda mutação.",
            "minimum": 0
          },
          "clickup_id": {
            "anyOf": [
              {
                "type": "string",
                "description": "Identificador externo/legado."
              },
              {
                "type": "null"
              }
            ]
          },
          "title": {
            "type": "string",
            "description": "Título editorial."
          },
          "channel": {
            "type": "string",
            "description": "Canal de publicação."
          },
          "status": {
            "type": "string",
            "description": "Estado do fluxo editorial."
          },
          "description": {
            "anyOf": [
              {
                "type": "string",
                "description": "Legenda ou descrição."
              },
              {
                "type": "null"
              }
            ]
          },
          "day": {
            "anyOf": [
              {
                "type": "integer",
                "description": "Dia no horário de Brasília.",
                "minimum": 1,
                "maximum": 31
              },
              {
                "type": "null"
              }
            ]
          },
          "month": {
            "anyOf": [
              {
                "type": "integer",
                "description": "Mês no horário de Brasília.",
                "minimum": 1,
                "maximum": 12
              },
              {
                "type": "null"
              }
            ]
          },
          "year": {
            "anyOf": [
              {
                "type": "integer",
                "description": "Ano no horário de Brasília."
              },
              {
                "type": "null"
              }
            ]
          },
          "due_at": {
            "anyOf": [
              {
                "type": "string",
                "description": "Data/hora ISO 8601 persistida.",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ]
          },
          "editorial_tag": {
            "anyOf": [
              {
                "type": "string",
                "description": "Tipo/tag editorial."
              },
              {
                "type": "null"
              }
            ]
          },
          "assignee_member_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "ID de membro."
            },
            "description": "Responsáveis por ID."
          },
          "assignees_names": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "Nome de membro."
            },
            "description": "Nomes dos responsáveis."
          }
        },
        "required": [
          "id",
          "title",
          "channel",
          "status"
        ],
        "additionalProperties": true,
        "description": "Evento editorial do calendário com token de revisão CAS."
      }
    }
  },
  "required": [
    "tarefas"
  ]
}
```

Example:

```json
{
  "tarefas": [
    {
      "id": "id-exemplo",
      "api_revision": 0,
      "clickup_id": "clickup-id-exemplo",
      "title": "Conteúdo editorial",
      "channel": "instagram",
      "status": "processing",
      "description": "Conteúdo de exemplo",
      "day": 1,
      "month": 1,
      "year": 1,
      "due_at": "2026-08-22T15:00:00.000Z",
      "editorial_tag": "string",
      "assignee_member_ids": [
        "assignee-member-id-exemplo"
      ],
      "assignees_names": [
        "Exemplo Hermes"
      ]
    }
  ]
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### POST /api/upload

Enviar arquivo pronto

Corpo binário, limite de 300 MB. Metadados seguem na query string.

Recebe bytes diretamente no corpo e armazena o arquivo. Metadados ficam na query string; use `Idempotency-Key` para evitar duplicatas em repetições.

- operationId: `uploadMedia`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `art`

#### Parameters

##### header Idempotency-Key

- required: false
- description: Chave opcional de 8 a 128 caracteres seguros. Repita a mesma chave somente com o mesmo payload; reutilização com conteúdo diferente retorna 409.

Schema:

```json
{
  "type": "string",
  "minLength": 8,
  "maxLength": 128,
  "pattern": "^[A-Za-z0-9._:~-]+$"
}
```

Example:

```json
"docs-20260822-001"
```

##### query event_id

- required: false
- description: Evento opcional.

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"string"
```

##### query filename

- required: false
- description: Nome usado também para detectar vídeo.

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"string"
```

##### query format

- required: false
- description: Proporção/formato.

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"string"
```

##### query kind

- required: false
- description: Tipo lógico.

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"string"
```

##### query slide_index

- required: false
- description: Ordem.

Schema:

```json
{
  "type": "integer",
  "default": 0
}
```

Example:

```json
0
```

#### Request body

- required: true
- description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema.

##### application/octet-stream

Schema:

```json
{
  "type": "string",
  "contentMediaType": "application/octet-stream"
}
```

Example:

```json
"<binary>"
```

##### image/*

Schema:

```json
{
  "type": "string",
  "contentMediaType": "image/*"
}
```

Example:

```json
"<binary>"
```

##### video/*

Schema:

```json
{
  "type": "string",
  "contentMediaType": "video/*"
}
```

Example:

```json
"<binary>"
```

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "ID."
    },
    "url": {
      "type": "string",
      "description": "URL pública.",
      "format": "uri"
    },
    "kind": {
      "type": "string",
      "description": "Tipo lógico."
    },
    "bytes": {
      "type": "integer",
      "description": "Tamanho recebido.",
      "minimum": 1
    }
  },
  "required": [
    "id",
    "url",
    "kind",
    "bytes"
  ],
  "description": "Resultado de um upload binário concluído."
}
```

Example:

```json
{
  "id": "id-exemplo",
  "url": "https://socialmedia.janvalellam.com.br/media/media-id?exp=1790000000&sig=assinatura",
  "kind": "string",
  "bytes": 1
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 404

Recurso não encontrado.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "recurso não encontrado"
}
```

##### 409

Operação conflita com o estado atual.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "conflito"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### GET /api/vendas/comercial

Consultar as vendas do time comercial e a comissão

Vendas com UTM `comercial` na Hotmart, no checkout Pagar.me e no Asaas, pela data do pedido, com a comissão de 4 % sobre as vendas novas (recorrências ficam fora). Mesmas regras da guia Comissão Nina da planilha de acerto. Só agregados, sem dados de compradores.

- operationId: `getCommercialSales`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `vendas`

#### Parameters

##### query from

- required: true
- description: Início do período.

Schema:

```json
{
  "type": "string",
  "description": "Primeiro dia do período (YYYY-MM-DD, horário de Brasília).",
  "format": "date"
}
```

Example:

```json
"2026-09-01"
```

##### query to

- required: true
- description: Fim do período, no máximo amanhã e até 730 dias depois de `from`.

Schema:

```json
{
  "type": "string",
  "description": "Último dia do período (YYYY-MM-DD, horário de Brasília).",
  "format": "date"
}
```

Example:

```json
"2026-09-30"
```

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Resumo do comercial no período.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "periodo": {
      "type": "object",
      "properties": {
        "from": {
          "type": "string",
          "description": "Início."
        },
        "to": {
          "type": "string",
          "description": "Fim."
        },
        "dias": {
          "type": "integer",
          "description": "Dias no período."
        }
      },
      "required": [
        "from",
        "to",
        "dias"
      ]
    },
    "pct_comissao": {
      "type": "number",
      "description": "Percentual da comissão sobre a base."
    },
    "totais": {
      "type": "object",
      "properties": {},
      "additionalProperties": true,
      "description": "qtd, vendido, novas, recorrentes, base_comissao, comissao e ticket do período."
    },
    "por_fonte": {
      "type": "object",
      "properties": {},
      "additionalProperties": true,
      "description": "Mesmo bloco por fonte: hotmart, pagarme, asaas."
    },
    "por_mes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "mes": {
            "type": "string",
            "description": "Mês YYYY-MM."
          }
        },
        "required": [
          "mes"
        ],
        "additionalProperties": true
      },
      "description": "Um bloco por mês do período, com o vendido por fonte."
    },
    "produtos": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "nome": {
            "type": "string",
            "description": "Produto."
          },
          "fonte": {
            "type": "string",
            "description": "Fonte."
          }
        },
        "required": [
          "nome",
          "fonte"
        ],
        "additionalProperties": true
      },
      "description": "Produtos vendidos pelo comercial, do maior para o menor."
    },
    "fontes": {
      "type": "object",
      "properties": {},
      "additionalProperties": true,
      "description": "Se cada fonte respondeu nesta consulta."
    },
    "avisos": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "Aviso operacional."
      },
      "description": "Lacunas e fallbacks aplicados."
    }
  },
  "required": [
    "periodo",
    "pct_comissao",
    "totais",
    "por_fonte",
    "por_mes",
    "produtos",
    "avisos"
  ]
}
```

Example:

```json
{
  "periodo": {
    "from": "string",
    "to": "string",
    "dias": 1
  },
  "pct_comissao": 1,
  "totais": {},
  "por_fonte": {},
  "por_mes": [
    {
      "mes": "string"
    }
  ],
  "produtos": [
    {
      "nome": "Exemplo Hermes",
      "fonte": "string"
    }
  ],
  "fontes": {},
  "avisos": [
    "string"
  ]
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

##### 503

Recurso não configurado neste servidor.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "painel de vendas não configurado neste servidor",
  "code": "VENDAS_NOT_CONFIGURED"
}
```

### GET /api/vendas/resumo

Consultar o resumo de vendas do período

Resumo financeiro consolidado do período (Hotmart, Shopify, Asaas e checkout Pagar.me) mais custos de mídia e ROAS. Exige a capability `vendas`, concedida pela permissão por pessoa `financeiro` (não pelo nível). Datas são dias em horário de Brasília, intervalo máximo de 730 dias; valores desconhecidos vêm como `null`, nunca como zero; a resposta nunca inclui dados pessoais de compradores e fica em cache por cinco minutos no servidor.

- operationId: `getSalesSummary`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `vendas`

#### Parameters

##### query from

- required: true
- description: Início do período.

Schema:

```json
{
  "type": "string",
  "description": "Primeiro dia do período (YYYY-MM-DD, horário de Brasília).",
  "format": "date"
}
```

Example:

```json
"2026-08-01"
```

##### query produtos

- required: false
- description: Quantos produtos listar por fonte.

Schema:

```json
{
  "type": "string",
  "description": "`top` (padrão, 15 por fonte) ou `all` (lista completa).",
  "enum": [
    "top",
    "all"
  ]
}
```

Example:

```json
"top"
```

##### query to

- required: true
- description: Fim do período, no máximo amanhã e até 730 dias depois de `from`.

Schema:

```json
{
  "type": "string",
  "description": "Último dia do período (YYYY-MM-DD, horário de Brasília).",
  "format": "date"
}
```

Example:

```json
"2026-08-31"
```

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Resumo agregado do período.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "periodo": {
      "type": "object",
      "properties": {
        "from": {
          "type": "string",
          "description": "Início."
        },
        "to": {
          "type": "string",
          "description": "Fim."
        },
        "dias": {
          "type": "integer",
          "description": "Dias no período."
        }
      },
      "required": [
        "from",
        "to",
        "dias"
      ]
    },
    "gerado_em": {
      "type": "string",
      "description": "Instante de geração.",
      "format": "date-time"
    },
    "cache": {
      "type": "object",
      "properties": {
        "hit": {
          "type": "boolean",
          "description": "Se veio do cache do servidor."
        },
        "ttl_s": {
          "type": "integer",
          "description": "Segundos restantes de cache."
        }
      },
      "required": [
        "hit",
        "ttl_s"
      ]
    },
    "atualizado_em": {
      "type": "object",
      "properties": {},
      "additionalProperties": {
        "anyOf": [
          {
            "type": "string",
            "description": "Último sync da tabela."
          },
          {
            "type": "null"
          }
        ]
      },
      "description": "Último sync por tabela de origem."
    },
    "totais": {
      "type": "object",
      "properties": {
        "bruto": {
          "type": "number",
          "description": "Faturamento bruto em BRL."
        },
        "liquido": {
          "type": "number",
          "description": "Líquido em BRL (Hotmart valor do produtor, Shopify após descontos e reembolsos, Asaas net, Pagar.me parte do JVE)."
        },
        "vendas": {
          "type": "integer",
          "description": "Quantidade de vendas."
        },
        "ticket_medio": {
          "anyOf": [
            {
              "type": "number",
              "description": "Bruto dividido por vendas."
            },
            {
              "type": "null"
            }
          ]
        },
        "investimento": {
          "anyOf": [
            {
              "type": "number",
              "description": "Custos de mídia em BRL."
            },
            {
              "type": "null"
            }
          ]
        },
        "roas": {
          "anyOf": [
            {
              "type": "number",
              "description": "Bruto dividido por investimento."
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "bruto",
        "liquido",
        "vendas"
      ]
    },
    "fontes": {
      "type": "object",
      "properties": {},
      "additionalProperties": true,
      "description": "Bloco por fonte: hotmart, shopify_livros, shopify_eventos, shopify_outros, asaas, pagarme."
    },
    "serie": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "dia": {
            "type": "string",
            "description": "Dia YYYY-MM-DD."
          }
        },
        "required": [
          "dia"
        ],
        "additionalProperties": true
      },
      "description": "Série diária por fonte com custo do dia."
    },
    "categorias": {
      "type": "object",
      "properties": {},
      "additionalProperties": true,
      "description": "Bloco por categoria: livros, cursos (com Orbum), eventos e youtube (estimado, convertido do dólar). Cada um com bruto, liquido_jve, comissao_trismegisto, qtd, ticket, composicao por plataforma e fontes_indisponiveis."
    },
    "totais_categorias": {
      "type": "object",
      "properties": {},
      "additionalProperties": true,
      "description": "Soma das quatro categorias (inclui o YouTube estimado) com ROAS sobre esse total."
    },
    "serie_categorias": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "dia": {
            "type": "string",
            "description": "Dia YYYY-MM-DD."
          }
        },
        "required": [
          "dia"
        ],
        "additionalProperties": true
      },
      "description": "Série diária de livros, cursos e eventos; o YouTube mensal vem em categorias.youtube.por_mes."
    },
    "produtos": {
      "type": "object",
      "properties": {},
      "additionalProperties": true,
      "description": "Top 15 produtos por fonte."
    },
    "intl": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "moeda": {
            "type": "string",
            "description": "Moeda ISO."
          }
        },
        "required": [
          "moeda"
        ],
        "additionalProperties": true
      },
      "description": "Vendas Hotmart fora do BRL, por moeda."
    },
    "custos": {
      "anyOf": [
        {
          "type": "object",
          "properties": {},
          "additionalProperties": true,
          "description": "Meta, Google e WhatsApp, por dia e por campanha, com ROAS."
        },
        {
          "type": "null"
        }
      ]
    },
    "avisos": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "Aviso operacional."
      },
      "description": "Lacunas e fallbacks aplicados."
    }
  },
  "required": [
    "periodo",
    "gerado_em",
    "totais",
    "fontes",
    "serie",
    "produtos",
    "intl",
    "avisos"
  ]
}
```

Example:

```json
{
  "periodo": {
    "from": "string",
    "to": "string",
    "dias": 1
  },
  "gerado_em": "2026-08-22T15:00:00.000Z",
  "cache": {
    "hit": true,
    "ttl_s": 1
  },
  "atualizado_em": {},
  "totais": {
    "bruto": 1,
    "liquido": 1,
    "vendas": 1,
    "ticket_medio": 1,
    "investimento": 1,
    "roas": 1
  },
  "fontes": {},
  "serie": [
    {
      "dia": "string"
    }
  ],
  "categorias": {},
  "totais_categorias": {},
  "serie_categorias": [
    {
      "dia": "string"
    }
  ],
  "produtos": {},
  "intl": [
    {
      "moeda": "string"
    }
  ],
  "custos": {},
  "avisos": [
    "string"
  ]
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

##### 503

Recurso não configurado neste servidor.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "painel de vendas não configurado neste servidor",
  "code": "VENDAS_NOT_CONFIGURED"
}
```

### GET /media/{id}

Baixar uma mídia pelo domínio do Hermes

Proxy público necessário para provedores que fazem pull da mídia por URL (Post for Me, TikTok PULL_FROM_URL). Não exige login, mas só abre com a assinatura `sig` e dentro da validade `exp` que o Hermes coloca na URL. O tipo retornado depende do asset.

Entrega um asset armazenado pelo Hermes para visualização ou consumo por provedores sociais. Use sempre a URL completa devolvida pelas operações de mídia: ela leva `exp` e `sig` e vale por 7 dias. Link sem assinatura, adulterado ou vencido recebe 403; peça a mídia de novo para obter um link novo.

- operationId: `getMedia`
- authentication: public

#### Parameters

##### path id

- required: true
- description: ID de media_assets.

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"string"
```

##### query exp

- required: true
- description: Validade do link em segundos Unix, emitida pelo Hermes.

Schema:

```json
{
  "type": "string",
  "pattern": "^\\d{1,12}$"
}
```

Example:

```json
"string"
```

##### query sig

- required: true
- description: Assinatura HMAC do link, emitida pelo Hermes.

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"string"
```

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Bytes da mídia.

###### application/octet-stream

Schema:

```json
{
  "type": "string",
  "contentMediaType": "application/octet-stream"
}
```

Example:

```json
"<bytes binários>"
```

##### 403

Link sem assinatura, adulterado ou vencido.

###### text/plain

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"link de mídia expirado ou inválido; gere um novo pelo Hermes"
```

##### 404

Mídia ou objeto de storage não encontrado; resposta sem corpo.

Schema: no response body.

Example: no response body.

##### 500

Falha interna; resposta sem corpo.

Schema: no response body.

Example: no response body.

### GET /oauth/_accounts

Listar provedores e contas conectadas

Nunca retorna tokens.

Retorna provedores habilitados e metadados seguros das contas conectadas. Tokens, refresh tokens e segredos nunca aparecem na resposta.

- operationId: `listOAuthAccounts`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `connections_view`

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "providers": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "Provedor disponível no ambiente."
      }
    },
    "accounts": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {},
        "additionalProperties": true
      },
      "description": "Contas conectadas, sem credenciais."
    }
  },
  "required": [
    "providers",
    "accounts"
  ]
}
```

Example:

```json
{
  "providers": [
    "meta"
  ],
  "accounts": [
    {}
  ]
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### GET /oauth/tiktok/creator-info

Consultar restrições do criador no TikTok

Consulta limites e opções de publicação da conta TikTok conectada, como privacidade e recursos permitidos, antes de preparar um envio.

- operationId: `getTikTokCreatorInfo`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `connections_view`

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Resposta normalizada do TikTok Creator Info.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": true
}
```

Example:

```json
{}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 404

Recurso não encontrado.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "recurso não encontrado"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### POST /oauth/tiktok/publish

Publicar conteúdo no TikTok

Aceita somente IDs de mídia do Hermes; URLs arbitrárias do cliente são rejeitadas pelo desenho da rota.

Publica foto ou vídeo usando exclusivamente IDs de mídia armazenados pelo Hermes. Valide antes as restrições retornadas por Creator Info.

- operationId: `publishTikTokContent`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `publish`

#### Parameters

No path, query, header, or cookie parameters.

#### Request body

- required: true
- description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema.

##### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "description": "Formato do post.",
      "enum": [
        "PHOTO",
        "VIDEO"
      ],
      "default": "PHOTO"
    },
    "caption": {
      "type": "string",
      "description": "Legenda."
    },
    "mediaIds": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "ID em media_assets."
      },
      "description": "IDs na ordem de publicação."
    },
    "privacy_level": {
      "type": "string",
      "description": "Privacidade solicitada. Em app não auditado o servidor força SELF_ONLY."
    },
    "disable_comment": {
      "type": "boolean",
      "description": "Desabilitar comentários."
    },
    "disable_duet": {
      "type": "boolean",
      "description": "Desabilitar duetos."
    },
    "disable_stitch": {
      "type": "boolean",
      "description": "Desabilitar stitch."
    },
    "brand_organic_toggle": {
      "type": "boolean",
      "description": "Marcar conteúdo promocional próprio."
    },
    "brand_content_toggle": {
      "type": "boolean",
      "description": "Marcar conteúdo de marca."
    },
    "auto_add_music": {
      "type": "boolean",
      "description": "Permitir música automática."
    }
  },
  "required": [
    "mediaIds"
  ]
}
```

Example:

```json
{
  "type": "PHOTO",
  "caption": "Legenda",
  "mediaIds": [
    "media-id"
  ],
  "privacy_level": "SELF_ONLY",
  "disable_comment": false,
  "disable_duet": false,
  "disable_stitch": false,
  "brand_organic_toggle": false,
  "brand_content_toggle": false,
  "auto_add_music": false
}
```

#### Responses

##### 200

Resposta do adaptador TikTok.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": true
}
```

Example:

```json
{}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 404

Recurso não encontrado.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "recurso não encontrado"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### GET /oauth/{provider}/callback

Concluir callback OAuth

O state HMAC expira em dez minutos, contém apenas vínculos opacos com usuário/membro e exige o cookie HttpOnly/Secure/SameSite=Lax do navegador iniciador. O cookie é apagado antes da troca do código.

Callback consumido pelo navegador após autorização no provedor. `state` e cookie precisam corresponder ao fluxo iniciado e expiram em dez minutos.

- operationId: `completeOAuthProvider`
- authentication: public

#### Parameters

##### path provider

- required: true
- description: Provedor social potencialmente disponível no ambiente.

Schema:

```json
{
  "type": "string",
  "enum": [
    "meta",
    "pinterest",
    "tiktok",
    "youtube"
  ]
}
```

Example:

```json
"meta"
```

##### query code

- required: true
- description: Código emitido pelo provedor.

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"provider-authorization-code"
```

##### query state

- required: true
- description: Estado HMAC emitido pela rota start.

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"signed-oauth-state"
```

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Conta conectada; texto para a janela OAuth.

###### text/html

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"Conta conectada!"
```

##### 400

Estado inválido ou expirado.

###### text/plain

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"Sessão de conexão inválida ou expirada."
```

##### 404

Provedor não suportado.

###### text/plain

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"rede não suportada: provider"
```

##### 500

Falha na troca do código ou persistência.

###### text/plain

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"Erro ao conectar: detalhe"
```

### POST /oauth/{provider}/disconnect

Desconectar um provedor social

Revoga a conexão persistida do provedor para a equipe. Depois da operação, confirme o estado com a consulta de contas antes de iniciar uma nova autorização.

- operationId: `disconnectOAuthProvider`
- authentication: Supabase session bearer token (session only)
- required capability: `connections`

#### Parameters

##### path provider

- required: true
- description: Provedor social potencialmente disponível no ambiente.

Schema:

```json
{
  "type": "string",
  "enum": [
    "meta",
    "pinterest",
    "tiktok",
    "youtube"
  ]
}
```

Example:

```json
"meta"
```

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Sucesso."
    }
  },
  "required": [
    "ok"
  ],
  "description": "Confirmação mínima de uma operação concluída."
}
```

Example:

```json
{
  "ok": true
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 500

Falha interna ou de integração.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da falha"
}
```

### POST /oauth/{provider}/start

Iniciar autorização OAuth

Exige administrador com capability connections. Cria state opaco ligado ao usuário/membro e cookie HttpOnly restrito ao callback; retorna a URL para um popup já aberto pelo front.

Inicia um fluxo OAuth vinculado ao usuário e membro atuais. Abra a URL retornada no navegador que iniciou a operação para preservar o cookie seguro do callback.

- operationId: `startOAuthProvider`
- authentication: Supabase session bearer token (session only)
- required capability: `connections`

#### Parameters

##### path provider

- required: true
- description: Provedor social potencialmente disponível no ambiente.

Schema:

```json
{
  "type": "string",
  "enum": [
    "meta",
    "pinterest",
    "tiktok",
    "youtube"
  ]
}
```

Example:

```json
"meta"
```

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Operação concluída.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "URL de autorização do provedor.",
      "format": "uri"
    }
  },
  "required": [
    "url"
  ]
}
```

Example:

```json
{
  "url": "https://socialmedia.janvalellam.com.br/media/media-id?exp=1790000000&sig=assinatura"
}
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 404

Provedor não suportado.

###### text/plain

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"rede não suportada: provider"
```

##### 500

Falha ao iniciar o fluxo OAuth.

###### text/plain

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"Internal Server Error"
```

### GET /oauth/{provider}/status

Exibir diagnóstico HTML da conexão

Página HTML de diagnóstico destinada ao navegador. Para integração programática, prefira a listagem JSON de contas conectadas.

- operationId: `getOAuthProviderStatus`
- authentication: Supabase session or `hms_live_` personal bearer token
- required capability: `connections_view`

#### Parameters

##### path provider

- required: true
- description: Provedor social potencialmente disponível no ambiente.

Schema:

```json
{
  "type": "string",
  "enum": [
    "meta",
    "pinterest",
    "tiktok",
    "youtube"
  ]
}
```

Example:

```json
"meta"
```

#### Request body

Schema: no request body.

Example: no request body.

#### Responses

##### 200

Página HTML de diagnóstico.

###### text/html

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"<!doctype html><html><body>Operação concluída.</body></html>"
```

##### 400

Entrada inválida.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "detalhe da validação"
}
```

##### 401

Token ausente, inválido ou falha de autenticação.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "não autenticado"
}
```

##### 403

Usuário fora da equipe ativa ou sem a capability necessária.

###### application/json

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "sem permissão para: capability"
}
```

##### 404

Provedor não suportado.

###### text/plain

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"rede não suportada: provider"
```

##### 500

Falha na consulta ao provedor.

###### text/plain

Schema:

```json
{
  "type": "string"
}
```

Example:

```json
"Erro: detalhe"
```

## Self-contained schemas

### AiManifest

Schema:

```json
{
  "type": "object",
  "properties": {
    "schema_version": {
      "type": "integer",
      "description": "Versão do formato.",
      "const": 1
    },
    "release": {
      "type": "object",
      "properties": {
        "version": {
          "type": "string",
          "description": "Versão da camada de IA."
        },
        "date": {
          "type": "string",
          "description": "Data ISO.",
          "format": "date"
        }
      },
      "required": [
        "version",
        "date"
      ]
    },
    "artifacts": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "ID estável."
          },
          "path": {
            "type": "string",
            "description": "Caminho no repositório."
          },
          "url": {
            "type": "string",
            "description": "URL pública.",
            "format": "uri"
          },
          "media_type": {
            "type": "string",
            "description": "MIME."
          },
          "bytes": {
            "type": "integer",
            "description": "Tamanho.",
            "minimum": 1
          },
          "sha256": {
            "type": "string",
            "description": "SHA-256 hexadecimal.",
            "pattern": "^[a-f0-9]{64}$"
          }
        },
        "required": [
          "id",
          "path",
          "url",
          "media_type",
          "bytes",
          "sha256"
        ]
      }
    },
    "skills": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Nome da skill."
          },
          "version": {
            "type": "string",
            "description": "Versão."
          },
          "artifact_id": {
            "type": "string",
            "description": "ID do ZIP."
          },
          "sha256": {
            "type": "string",
            "description": "SHA-256 do ZIP."
          }
        },
        "required": [
          "name",
          "version",
          "artifact_id",
          "sha256"
        ]
      }
    }
  },
  "required": [
    "schema_version",
    "release",
    "artifacts",
    "skills"
  ],
  "description": "Catálogo verificável dos artefatos públicos da camada de IA."
}
```

Example:

```json
{
  "schema_version": 1,
  "release": {
    "version": "string",
    "date": "2026-09-02"
  },
  "artifacts": [
    {
      "id": "string",
      "path": "string",
      "url": "https://socialmedia.janvalellam.com.br/resource",
      "media_type": "string",
      "bytes": 1,
      "sha256": "string"
    }
  ],
  "skills": [
    {
      "name": "string",
      "version": "string",
      "artifact_id": "string",
      "sha256": "string"
    }
  ]
}
```

### ApiAccessLevel

Schema:

```json
{
  "type": "string",
  "description": "Nível individual configurável somente para tokens pessoais da API; não limita sessões do Studio.",
  "enum": [
    "nenhum",
    "leitor",
    "criador",
    "lider",
    "admin"
  ]
}
```

Example:

```json
"nenhum"
```

### ApiAccessMember

Schema:

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "ID do membro."
    },
    "name": {
      "type": "string",
      "description": "Nome."
    },
    "email": {
      "anyOf": [
        {
          "type": "string",
          "description": "E-mail.",
          "format": "email"
        },
        {
          "type": "null"
        }
      ]
    },
    "access_level": {
      "type": "string",
      "description": "Cargo atual no Studio; governa sessões e funciona como teto do PAT.",
      "enum": [
        "criador",
        "lider",
        "admin"
      ]
    },
    "api_access_level": {
      "type": "string",
      "description": "Nível individual configurável somente para tokens pessoais da API; não limita sessões do Studio.",
      "enum": [
        "nenhum",
        "leitor",
        "criador",
        "lider",
        "admin"
      ]
    },
    "effective_api_access_level": {
      "type": "string",
      "description": "Nível individual configurável somente para tokens pessoais da API; não limita sessões do Studio.",
      "enum": [
        "nenhum",
        "leitor",
        "criador",
        "lider",
        "admin"
      ]
    },
    "capabilities": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "Capability efetiva disponível para tokens pessoais; não descreve nem limita a sessão do Studio."
      }
    },
    "token_count": {
      "type": "integer",
      "description": "Quantidade de tokens ativos.",
      "minimum": 0,
      "maximum": 10
    },
    "tokens": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "ID público usado para revogação."
          },
          "label": {
            "type": "string",
            "description": "Nome legível definido pelo usuário."
          },
          "prefix": {
            "type": "string",
            "description": "Prefixo identificável sem a parte secreta.",
            "pattern": "^hms_live_[A-Za-z0-9_-]{16}$"
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "Capability concedida ao token."
            },
            "description": "Scopes persistidos em ordem determinística."
          },
          "created_at": {
            "type": "string",
            "description": "Criação ISO.",
            "format": "date-time"
          },
          "expires_at": {
            "type": "string",
            "description": "Expiração ISO.",
            "format": "date-time"
          },
          "last_used_at": {
            "anyOf": [
              {
                "type": "string",
                "description": "Último uso observado, atualizado de forma best effort.",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ]
          },
          "revoked_at": {
            "anyOf": [
              {
                "type": "string",
                "description": "Revogação ISO, quando aplicável.",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ]
          },
          "status": {
            "type": "string",
            "description": "Estado derivado no momento da leitura.",
            "enum": [
              "active",
              "expired",
              "revoked"
            ]
          }
        },
        "required": [
          "id",
          "label",
          "prefix",
          "scopes",
          "created_at",
          "expires_at",
          "last_used_at",
          "revoked_at",
          "status"
        ],
        "description": "Metadados revogáveis de um token pessoal sem segredo nem hash."
      }
    }
  },
  "required": [
    "id",
    "name",
    "access_level",
    "api_access_level",
    "effective_api_access_level",
    "capabilities",
    "token_count",
    "tokens"
  ],
  "description": "Visão administrativa do cargo do Studio e da camada separada de tokens pessoais de um membro ativo."
}
```

Example:

```json
{
  "id": "string",
  "name": "string",
  "access_level": "criador",
  "api_access_level": "nenhum",
  "effective_api_access_level": "nenhum",
  "capabilities": [
    "string"
  ],
  "token_count": 0,
  "tokens": [
    {
      "id": "string",
      "label": "string",
      "prefix": "string",
      "scopes": [
        "string"
      ],
      "created_at": "2026-09-02T15:00:00.000Z",
      "expires_at": "2026-09-02T15:00:00.000Z",
      "last_used_at": "2026-09-02T15:00:00.000Z",
      "revoked_at": "2026-09-02T15:00:00.000Z",
      "status": "active"
    }
  ]
}
```

### ApiAccessSelfMember

Schema:

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "ID do membro."
    },
    "name": {
      "type": "string",
      "description": "Nome."
    },
    "email": {
      "anyOf": [
        {
          "type": "string",
          "description": "E-mail.",
          "format": "email"
        },
        {
          "type": "null"
        }
      ]
    },
    "access_level": {
      "type": "string",
      "description": "Cargo atual no Studio; governa a sessão e funciona como teto do PAT.",
      "enum": [
        "criador",
        "lider",
        "admin"
      ]
    },
    "financeiro": {
      "type": "boolean",
      "description": "Permissão por pessoa: vê o painel de Vendas."
    },
    "api_access_level": {
      "type": "string",
      "description": "Nível individual configurável somente para tokens pessoais da API; não limita sessões do Studio.",
      "enum": [
        "nenhum",
        "leitor",
        "criador",
        "lider",
        "admin"
      ]
    },
    "effective_api_access_level": {
      "type": "string",
      "description": "Nível individual configurável somente para tokens pessoais da API; não limita sessões do Studio.",
      "enum": [
        "nenhum",
        "leitor",
        "criador",
        "lider",
        "admin"
      ]
    }
  },
  "required": [
    "id",
    "name",
    "access_level",
    "api_access_level",
    "effective_api_access_level"
  ],
  "description": "Resumo da configuração de tokens pessoais do membro; não limita a sessão atual do Studio."
}
```

Example:

```json
{
  "id": "string",
  "name": "string",
  "access_level": "criador",
  "api_access_level": "nenhum",
  "effective_api_access_level": "nenhum"
}
```

### ApiAuditEvent

Schema:

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "ID do evento de auditoria."
    },
    "occurred_at": {
      "type": "string",
      "description": "Data/hora do evento.",
      "format": "date-time"
    },
    "request_id": {
      "anyOf": [
        {
          "type": "string",
          "description": "Correlação segura da requisição."
        },
        {
          "type": "null"
        }
      ]
    },
    "actor_member_id": {
      "anyOf": [
        {
          "type": "string",
          "description": "Membro autor."
        },
        {
          "type": "null"
        }
      ]
    },
    "actor_user_id": {
      "anyOf": [
        {
          "type": "string",
          "description": "Usuário Supabase autor."
        },
        {
          "type": "null"
        }
      ]
    },
    "token_id": {
      "anyOf": [
        {
          "type": "string",
          "description": "ID de metadados do token pessoal, nunca o segredo ou hash."
        },
        {
          "type": "null"
        }
      ]
    },
    "auth_method": {
      "type": "string",
      "description": "Método de autenticação observado.",
      "enum": [
        "session",
        "personal_token",
        "system",
        "anonymous"
      ]
    },
    "capability": {
      "anyOf": [
        {
          "type": "string",
          "description": "Capability avaliada."
        },
        {
          "type": "null"
        }
      ]
    },
    "action": {
      "type": "string",
      "description": "Ação normalizada."
    },
    "resource_type": {
      "anyOf": [
        {
          "type": "string",
          "description": "Tipo lógico do recurso."
        },
        {
          "type": "null"
        }
      ]
    },
    "resource_id": {
      "anyOf": [
        {
          "type": "string",
          "description": "ID lógico do recurso."
        },
        {
          "type": "null"
        }
      ]
    },
    "outcome": {
      "type": "string",
      "description": "Resultado normalizado.",
      "enum": [
        "allowed",
        "denied",
        "succeeded",
        "failed"
      ]
    },
    "status_code": {
      "anyOf": [
        {
          "type": "integer",
          "description": "Status HTTP relacionado.",
          "minimum": 100,
          "maximum": 599
        },
        {
          "type": "null"
        }
      ]
    },
    "metadata": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "id",
    "occurred_at",
    "auth_method",
    "action",
    "outcome",
    "metadata"
  ],
  "description": "Evento sanitizado da trilha de autorização e gestão de acesso à API."
}
```

Example:

```json
{
  "id": "string",
  "occurred_at": "2026-09-02T15:00:00.000Z",
  "auth_method": "session",
  "action": "string",
  "outcome": "allowed",
  "metadata": {}
}
```

### AuthContext

Schema:

```json
{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "description": "Método que autenticou a chamada.",
      "enum": [
        "session",
        "api_token"
      ]
    },
    "token_id": {
      "anyOf": [
        {
          "type": "string",
          "description": "ID do token pessoal quando kind é api_token."
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "kind",
    "token_id"
  ],
  "description": "Método efetivamente usado para autenticar a requisição atual."
}
```

Example:

```json
{
  "kind": "session",
  "token_id": "string"
}
```

### ConfigEntry

Schema:

```json
{
  "type": "object",
  "properties": {
    "value": {},
    "version": {
      "type": "integer",
      "description": "Versão."
    },
    "updated_at": {
      "anyOf": [
        {
          "type": "string",
          "description": "Atualização ISO.",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "value",
    "version"
  ],
  "description": "Versão mais recente de uma configuração."
}
```

Example:

```json
{
  "value": {},
  "version": 0
}
```

### EmailDraft

Schema:

```json
{
  "type": "object",
  "properties": {
    "template_id": {
      "type": "string",
      "description": "ID lógico do template."
    },
    "html": {
      "type": "string",
      "description": "HTML completo."
    },
    "metadata": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    },
    "updated_at": {
      "type": "string",
      "description": "Token CAS.",
      "format": "date-time"
    },
    "updated_by": {
      "type": "string",
      "description": "Usuário editor."
    }
  },
  "required": [
    "template_id",
    "html",
    "metadata",
    "updated_at",
    "updated_by"
  ],
  "description": "Template de e-mail completo com token CAS baseado em timestamp."
}
```

Example:

```json
{
  "template_id": "string",
  "html": "string",
  "metadata": {},
  "updated_at": "2026-09-02T15:00:00.000Z",
  "updated_by": "string"
}
```

### EmailDraftSummary

Schema:

```json
{
  "type": "object",
  "properties": {
    "template_id": {
      "type": "string",
      "description": "ID lógico do template."
    },
    "metadata": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    },
    "updated_at": {
      "type": "string",
      "description": "Token CAS.",
      "format": "date-time"
    },
    "updated_by": {
      "type": "string",
      "description": "Usuário editor."
    }
  },
  "required": [
    "template_id",
    "metadata",
    "updated_at",
    "updated_by"
  ],
  "description": "Metadados leves de um rascunho, sem o HTML completo."
}
```

Example:

```json
{
  "template_id": "string",
  "metadata": {},
  "updated_at": "2026-09-02T15:00:00.000Z",
  "updated_by": "string"
}
```

### Error

Schema:

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Mensagem segura para diagnóstico."
    },
    "code": {
      "type": "string",
      "description": "Código estável opcional."
    },
    "details": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    }
  },
  "required": [
    "error"
  ],
  "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável."
}
```

Example:

```json
{
  "error": "string"
}
```

### Event

Schema:

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Identificador do evento."
    },
    "api_revision": {
      "type": "integer",
      "description": "Token CAS da API; releia o evento antes de toda mutação.",
      "minimum": 0
    },
    "clickup_id": {
      "anyOf": [
        {
          "type": "string",
          "description": "Identificador externo/legado."
        },
        {
          "type": "null"
        }
      ]
    },
    "title": {
      "type": "string",
      "description": "Título editorial."
    },
    "channel": {
      "type": "string",
      "description": "Canal de publicação."
    },
    "status": {
      "type": "string",
      "description": "Estado do fluxo editorial."
    },
    "description": {
      "anyOf": [
        {
          "type": "string",
          "description": "Legenda ou descrição."
        },
        {
          "type": "null"
        }
      ]
    },
    "day": {
      "anyOf": [
        {
          "type": "integer",
          "description": "Dia no horário de Brasília.",
          "minimum": 1,
          "maximum": 31
        },
        {
          "type": "null"
        }
      ]
    },
    "month": {
      "anyOf": [
        {
          "type": "integer",
          "description": "Mês no horário de Brasília.",
          "minimum": 1,
          "maximum": 12
        },
        {
          "type": "null"
        }
      ]
    },
    "year": {
      "anyOf": [
        {
          "type": "integer",
          "description": "Ano no horário de Brasília."
        },
        {
          "type": "null"
        }
      ]
    },
    "due_at": {
      "anyOf": [
        {
          "type": "string",
          "description": "Data/hora ISO 8601 persistida.",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ]
    },
    "editorial_tag": {
      "anyOf": [
        {
          "type": "string",
          "description": "Tipo/tag editorial."
        },
        {
          "type": "null"
        }
      ]
    },
    "assignee_member_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "ID de membro."
      },
      "description": "Responsáveis por ID."
    },
    "assignees_names": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "Nome de membro."
      },
      "description": "Nomes dos responsáveis."
    }
  },
  "required": [
    "id",
    "title",
    "channel",
    "status"
  ],
  "additionalProperties": true,
  "description": "Evento editorial do calendário com token de revisão CAS."
}
```

Example:

```json
{
  "id": "string",
  "title": "string",
  "channel": "string",
  "status": "string"
}
```

### MediaReference

Schema:

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "ID."
    },
    "url": {
      "type": "string",
      "description": "URL pública no Hermes.",
      "format": "uri"
    },
    "slide_index": {
      "type": "integer",
      "description": "Ordem."
    },
    "kind": {
      "type": "string",
      "description": "Tipo lógico."
    }
  },
  "required": [
    "id",
    "url"
  ],
  "additionalProperties": true,
  "description": "Referência pública e ordenável de uma mídia persistida."
}
```

Example:

```json
{
  "id": "string",
  "url": "https://socialmedia.janvalellam.com.br/resource"
}
```

### Member

Schema:

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "ID."
    },
    "name": {
      "type": "string",
      "description": "Nome."
    },
    "email": {
      "type": "string",
      "description": "E-mail.",
      "format": "email"
    },
    "role": {
      "anyOf": [
        {
          "type": "string",
          "description": "Função."
        },
        {
          "type": "null"
        }
      ]
    },
    "access_level": {
      "type": "string",
      "description": "Cargo no Studio.",
      "enum": [
        "criador",
        "lider",
        "admin"
      ]
    },
    "api_access_level": {
      "type": "string",
      "description": "Nível individual configurável somente para tokens pessoais da API; não limita sessões do Studio.",
      "enum": [
        "nenhum",
        "leitor",
        "criador",
        "lider",
        "admin"
      ]
    },
    "is_admin": {
      "type": "boolean",
      "description": "Compatibilidade com legado."
    },
    "financeiro": {
      "type": "boolean",
      "description": "Permissão por pessoa: vê o painel de Vendas (capability `vendas`)."
    }
  },
  "required": [
    "id",
    "name",
    "email",
    "access_level"
  ],
  "description": "Membro ativo que pode receber atribuições e capabilities."
}
```

Example:

```json
{
  "id": "string",
  "name": "string",
  "email": "colaborador@example.com",
  "access_level": "criador"
}
```

### MemberIdentity

Schema:

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "ID do membro."
    },
    "user_id": {
      "type": "string",
      "description": "ID do usuário Supabase vinculado."
    },
    "name": {
      "type": "string",
      "description": "Nome."
    },
    "email": {
      "anyOf": [
        {
          "type": "string",
          "description": "E-mail do membro.",
          "format": "email"
        },
        {
          "type": "null"
        }
      ]
    },
    "access_level": {
      "type": "string",
      "description": "Nível desta credencial: cargo do Studio para session; nível PAT efetivo para api_token.",
      "enum": [
        "nenhum",
        "leitor",
        "criador",
        "lider",
        "admin"
      ]
    },
    "team_access_level": {
      "type": "string",
      "description": "Cargo atual no Studio; governa a sessão e serve de teto somente para PAT.",
      "enum": [
        "criador",
        "lider",
        "admin"
      ]
    },
    "api_access_level": {
      "type": "string",
      "description": "Configuração de PAT na sessão; nível PAT efetivo quando auth.kind é api_token.",
      "enum": [
        "nenhum",
        "leitor",
        "criador",
        "lider",
        "admin"
      ]
    }
  },
  "required": [
    "id",
    "name",
    "access_level",
    "team_access_level",
    "api_access_level"
  ],
  "description": "Identidade e autorização da credencial atual: cargo do Studio para sessão ou nível efetivo para PAT."
}
```

Example:

```json
{
  "id": "string",
  "name": "string",
  "access_level": "nenhum",
  "team_access_level": "criador",
  "api_access_level": "nenhum"
}
```

### MemberOffboardingResult

Schema:

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Todas as limpezas terminaram."
    },
    "accessRevoked": {
      "type": "boolean",
      "description": "Acesso revogado."
    },
    "alreadyInactive": {
      "type": "boolean",
      "description": "Já estava inativo."
    },
    "retryable": {
      "type": "boolean",
      "description": "Uma repetição é segura."
    },
    "member": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "ID."
        },
        "name": {
          "type": "string",
          "description": "Nome."
        },
        "email": {
          "type": "string",
          "description": "E-mail.",
          "format": "email"
        }
      },
      "required": [
        "id",
        "name",
        "email"
      ]
    },
    "summary": {
      "type": "object",
      "properties": {
        "events": {
          "type": "integer",
          "description": "Eventos alterados."
        },
        "tasks": {
          "type": "integer",
          "description": "Tarefas desatribuídas."
        },
        "comments": {
          "type": "integer",
          "description": "Comentários alterados."
        },
        "platforms": {
          "type": "integer",
          "description": "Plataformas alteradas."
        },
        "projects": {
          "type": "integer",
          "description": "Projetos alterados."
        },
        "authBan": {
          "type": "object",
          "properties": {},
          "additionalProperties": true
        }
      },
      "required": [
        "events",
        "tasks",
        "comments",
        "platforms",
        "projects",
        "authBan"
      ]
    },
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "scope": {
            "type": "string",
            "description": "Escopo."
          },
          "error": {
            "type": "string",
            "description": "Erro."
          }
        },
        "required": [
          "scope",
          "error"
        ]
      }
    }
  },
  "required": [
    "ok",
    "accessRevoked",
    "alreadyInactive",
    "retryable",
    "member",
    "summary",
    "errors"
  ],
  "description": "Relatório do desligamento seguro e das limpezas de atribuição."
}
```

Example:

```json
{
  "ok": false,
  "accessRevoked": false,
  "alreadyInactive": false,
  "retryable": false,
  "member": {
    "id": "string",
    "name": "string",
    "email": "colaborador@example.com"
  },
  "summary": {
    "events": 0,
    "tasks": 0,
    "comments": 0,
    "platforms": 0,
    "projects": 0,
    "authBan": {}
  },
  "errors": [
    {
      "scope": "string",
      "error": "string"
    }
  ]
}
```

### OkResponse

Schema:

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "Sucesso."
    }
  },
  "required": [
    "ok"
  ],
  "description": "Confirmação mínima de uma operação concluída."
}
```

Example:

```json
{
  "ok": false
}
```

### PersonalApiTokenMetadata

Schema:

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "ID público usado para revogação."
    },
    "label": {
      "type": "string",
      "description": "Nome legível definido pelo usuário."
    },
    "prefix": {
      "type": "string",
      "description": "Prefixo identificável sem a parte secreta.",
      "pattern": "^hms_live_[A-Za-z0-9_-]{16}$"
    },
    "scopes": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "Capability concedida ao token."
      },
      "description": "Scopes persistidos em ordem determinística."
    },
    "created_at": {
      "type": "string",
      "description": "Criação ISO.",
      "format": "date-time"
    },
    "expires_at": {
      "type": "string",
      "description": "Expiração ISO.",
      "format": "date-time"
    },
    "last_used_at": {
      "anyOf": [
        {
          "type": "string",
          "description": "Último uso observado, atualizado de forma best effort.",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ]
    },
    "revoked_at": {
      "anyOf": [
        {
          "type": "string",
          "description": "Revogação ISO, quando aplicável.",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ]
    },
    "status": {
      "type": "string",
      "description": "Estado derivado no momento da leitura.",
      "enum": [
        "active",
        "expired",
        "revoked"
      ]
    }
  },
  "required": [
    "id",
    "label",
    "prefix",
    "scopes",
    "created_at",
    "expires_at",
    "last_used_at",
    "revoked_at",
    "status"
  ],
  "description": "Metadados revogáveis de um token pessoal sem segredo nem hash."
}
```

Example:

```json
{
  "id": "string",
  "label": "string",
  "prefix": "string",
  "scopes": [
    "string"
  ],
  "created_at": "2026-09-02T15:00:00.000Z",
  "expires_at": "2026-09-02T15:00:00.000Z",
  "last_used_at": "2026-09-02T15:00:00.000Z",
  "revoked_at": "2026-09-02T15:00:00.000Z",
  "status": "active"
}
```

### Project

Schema:

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "ID do projeto."
    },
    "name": {
      "type": "string",
      "description": "Nome."
    },
    "payload": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    },
    "api_revision": {
      "type": "integer",
      "description": "Token CAS canônico.",
      "minimum": 0
    },
    "revision": {
      "type": "integer",
      "description": "Alias de api_revision.",
      "minimum": 0
    },
    "created_at": {
      "type": "string",
      "description": "Criação ISO.",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "description": "Atualização ISO.",
      "format": "date-time"
    },
    "created_by": {
      "type": "string",
      "description": "Usuário criador."
    },
    "updated_by": {
      "type": "string",
      "description": "Último usuário editor."
    }
  },
  "required": [
    "id",
    "name",
    "payload",
    "api_revision",
    "revision",
    "created_at",
    "updated_at",
    "created_by",
    "updated_by"
  ],
  "description": "Documento colaborativo de projeto e seus tokens de concorrência."
}
```

Example:

```json
{
  "id": "string",
  "name": "string",
  "payload": {},
  "api_revision": 0,
  "revision": 0,
  "created_at": "2026-09-02T15:00:00.000Z",
  "updated_at": "2026-09-02T15:00:00.000Z",
  "created_by": "string",
  "updated_by": "string"
}
```

### ProjectOperationLog

Schema:

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "ID da operação."
    },
    "payload_revision": {
      "type": "integer",
      "description": "Revisão produzida.",
      "minimum": 0
    },
    "operation_type": {
      "type": "string",
      "description": "Tipo."
    },
    "operation": {
      "type": "object",
      "properties": {},
      "additionalProperties": true
    },
    "actor_member_id": {
      "type": "string",
      "description": "Membro autor."
    },
    "actor_user_id": {
      "type": "string",
      "description": "Usuário autor."
    },
    "created_at": {
      "type": "string",
      "description": "Data ISO.",
      "format": "date-time"
    }
  },
  "required": [
    "id",
    "payload_revision",
    "operation_type",
    "operation",
    "created_at"
  ],
  "description": "Registro imutável de uma operação já aplicada ao projeto."
}
```

Example:

```json
{
  "id": "string",
  "payload_revision": 0,
  "operation_type": "string",
  "operation": {},
  "created_at": "2026-09-02T15:00:00.000Z"
}
```

### ProjectOperationRequest

Schema:

```json
{
  "type": "object",
  "properties": {
    "expected_revision": {
      "type": "integer",
      "description": "api_revision da leitura mais recente.",
      "minimum": 0
    },
    "expected_updated_at": {
      "type": "string",
      "description": "Token timestamp adicional opcional.",
      "format": "date-time"
    },
    "operation": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "description": "Tipo semântico da operação.",
          "enum": [
            "meta.update",
            "goal.add",
            "goal.update",
            "goal.remove",
            "goal.reorder",
            "task.add",
            "task.update",
            "task.remove",
            "task.reorder",
            "task.assignees.set",
            "subtask.add",
            "subtask.update",
            "subtask.remove",
            "subtask.reorder",
            "subtask.assignees.set",
            "comment.add",
            "comment.update",
            "comment.remove"
          ]
        }
      },
      "required": [
        "type"
      ],
      "additionalProperties": true
    }
  },
  "required": [
    "expected_revision",
    "operation"
  ],
  "description": "Envelope de uma alteração semântica e atômica de projeto."
}
```

Example:

```json
{
  "expected_revision": 0,
  "operation": {
    "type": "meta.update"
  }
}
```

### RagResponse

Schema:

```json
{
  "type": "object",
  "properties": {
    "contexto": {
      "type": "string",
      "description": "Contexto consolidado."
    },
    "fontes": {
      "anyOf": [
        {},
        {
          "type": "null"
        }
      ]
    },
    "resultados": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "titulo": {
            "anyOf": [
              {
                "type": "string",
                "description": "Título."
              },
              {
                "type": "null"
              }
            ]
          },
          "fonte": {
            "anyOf": [
              {
                "type": "string",
                "description": "Fonte."
              },
              {
                "type": "null"
              }
            ]
          },
          "texto": {
            "type": "string",
            "description": "Trecho."
          },
          "citacao": {
            "type": "object",
            "properties": {
              "pagina": {
                "type": "integer",
                "description": "Página detectada."
              }
            },
            "additionalProperties": false
          }
        },
        "required": [
          "texto",
          "citacao"
        ]
      }
    }
  },
  "required": [
    "contexto",
    "resultados"
  ],
  "description": "Contexto e evidências retornados pela pesquisa no Cérebro."
}
```

Example:

```json
{
  "contexto": "string",
  "resultados": [
    {
      "texto": "string",
      "citacao": {}
    }
  ]
}
```

### ReelJob

Schema:

```json
{
  "type": "object",
  "properties": {
    "state": {
      "type": "string",
      "description": "Estado."
    },
    "error": {
      "anyOf": [
        {
          "type": "string",
          "description": "Erro do worker."
        },
        {
          "type": "null"
        }
      ]
    },
    "url": {
      "type": "string",
      "description": "URL quando concluído.",
      "format": "uri"
    }
  },
  "required": [
    "state"
  ],
  "description": "Estado observável de uma geração de vídeo."
}
```

Example:

```json
{
  "state": "string"
}
```

### ReelJobAccepted

Schema:

```json
{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string",
      "description": "ID do job."
    },
    "state": {
      "type": "string",
      "description": "Estado.",
      "const": "processing"
    },
    "aviso": {
      "type": "string",
      "description": "Orientação de polling."
    }
  },
  "required": [
    "job_id",
    "state",
    "aviso"
  ],
  "description": "Confirmação de que a geração assíncrona de vídeo entrou na fila."
}
```

Example:

```json
{
  "job_id": "string",
  "state": "processing",
  "aviso": "string"
}
```

### Skill

Schema:

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Nome."
    },
    "content": {
      "type": "string",
      "description": "Conteúdo."
    },
    "version": {
      "type": "integer",
      "description": "Versão."
    },
    "updated_at": {
      "anyOf": [
        {
          "type": "string",
          "description": "Atualização ISO.",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "name",
    "content",
    "version"
  ],
  "description": "Conteúdo versionado de uma skill publicada no backend."
}
```

Example:

```json
{
  "name": "string",
  "content": "string",
  "version": 0
}
```

### StoredMedia

Schema:

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "ID."
    },
    "url": {
      "type": "string",
      "description": "URL pública.",
      "format": "uri"
    },
    "storage_path": {
      "type": "string",
      "description": "Caminho interno sem credenciais."
    }
  },
  "required": [
    "id",
    "url",
    "storage_path"
  ],
  "description": "Resultado de mídia gerada e armazenada pelo Hermes."
}
```

Example:

```json
{
  "id": "string",
  "url": "https://socialmedia.janvalellam.com.br/resource",
  "storage_path": "string"
}
```

### UploadedMedia

Schema:

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "ID."
    },
    "url": {
      "type": "string",
      "description": "URL pública.",
      "format": "uri"
    },
    "kind": {
      "type": "string",
      "description": "Tipo lógico."
    },
    "bytes": {
      "type": "integer",
      "description": "Tamanho recebido.",
      "minimum": 1
    }
  },
  "required": [
    "id",
    "url",
    "kind",
    "bytes"
  ],
  "description": "Resultado de um upload binário concluído."
}
```

Example:

```json
{
  "id": "string",
  "url": "https://socialmedia.janvalellam.com.br/resource",
  "kind": "string",
  "bytes": 1
}
```
