openapi: 3.1.0 info: title: API do Dashboard Mágico version: 1.0.0 description: |- Você que é dev, divirta-se! ✨ > **Índice da documentação** — acesse o índice completo em [https://docs.dashboards.kobana.com.br/llms.txt](https://docs.dashboards.kobana.com.br/llms.txt). Use este arquivo para descobrir todas as páginas disponíveis antes de explorar. > **Atenção às versões da API** — você está na documentação da **v1.0** da API do Dashboard Mágico, que cobre a organização, os usuários do portal e a equipe do dashboard. Recursos como **Pagamentos, Transferências, Extrato e Recebimento por Pix** seguem disponíveis em outras APIs da Kobana — use o seletor de produto no menu superior para acessá-las. ## Formato A API aceita apenas o formato `JSON`. Todas as requisições devem usar `Content-Type: application/json`. Todas as respostas usam `snake_case`. | Tipo de Campo | Formato | | :--- | :--- | | **DateTime** | Formato [ISO8601](https://pt.wikipedia.org/wiki/ISO_8601). Exemplos — Data: `2026-01-24`. Data e Hora: `2026-01-24T10:07Z` | | **UUID** | Identificadores de recursos no formato UUID v4 | ## Convenções Convenções usadas nesta documentação: | Convenção | Descrição | | :--- | :--- | | **`:variable`** | Nome de variável que precisa ser substituída em uma URL. | | **`#{variable}`** | Nome de variável que precisa ser substituída por valores da sua conta. | | **`...`** | Conteúdo da resposta truncado para facilitar a leitura. | | **`$KOBANA_TOKEN`** | Token de acesso. Para testes em linha de comando, exporte-o: `export KOBANA_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxx` e cole os comandos da documentação no terminal. | ## Códigos de Retorno A API retorna códigos HTTP padrão: | | Código | Descrição | | :--- | :--- | :--- | | ✅ | **200 OK** | Requisição bem-sucedida com corpo de resposta. | | ✅ | **201 Created** | Recurso criado com sucesso. | | ✅ | **204 No Content** | Requisição bem-sucedida, sem corpo de resposta. | | ❌ | **400 Bad Request** | Requisição inválida, em geral conteúdo mal formado. | | ❌ | **401 Unauthorized** | Token de acesso ausente ou inválido. | | ❌ | **403 Forbidden** | Acesso à API bloqueado ou usuário sem permissão. | | ❌ | **404 Not Found** | Endereço acessado não existe. | | ❌ | **422 Unprocessable Entity** | Requisição válida, mas os dados enviados não são. | | ❌ | **429 Too Many Requests** | Limite de requisições atingido. | | ❌ | **500 Internal Server Error** | Erro interno no processamento. Consulte o [status dos servidores](https://status.kobana.com.br). | ## ID das Requisições (Request ID) Cada requisição possui um identificador associado, disponível no cabeçalho `Request-Id` da resposta. Esse valor ajuda na depuração e auditoria — as requisições e seus IDs podem ser consultadas no painel do sistema. O log de requisições fica disponível por **30 dias**. Ao abrir um chamado de suporte sobre uma requisição específica, informe o `Request-Id` para acelerar a investigação. ## Segurança A API da Kobana usa certificados **SSL 2048 bits**. Toda requisição deve ser feita via **HTTPS** — chamadas na porta 80 são redirecionadas para 443. Os clientes devem suportar `TLSv1.2` ou `TLSv1.3` com uma das cifras: `TLS_AES_128_GCM_SHA256`, `TLS_AES_256_GCM_SHA384`, `TLS_CHACHA20_POLY1305_SHA256`, `ECDHE-RSA-AES128-GCM-SHA256`, `ECDHE-RSA-AES128-SHA256`, `ECDHE-RSA-AES256-GCM-SHA384`, `ECDHE-RSA-CHACHA20-POLY1305`, `ECDHE-RSA-AES256-SHA384`. `TLSv1` e `TLSv1.1` não são suportados. ## Cache HTTP Use os cabeçalhos HTTP de cache para reduzir carga e ganhar velocidade. A maioria das respostas inclui `ETag` e/ou `Last-Modified` — armazene esses valores e reenvie nas próximas requisições via `If-None-Match` e `If-Modified-Since`. Se o recurso não mudou, a resposta será `304 Not Modified`, sem corpo e sem reprocessamento. Mais informações: [HTTP Cache Docs](http://www.mnot.net/cache_docs/). ## Tratamento de Erros Erros 5xx indicam falhas no servidor: **500 Internal Server Error** (aplicação indisponível), **502 Bad Gateway**, **503 Service Unavailable** e **504 Gateway Timeout** (falhas pontuais de infraestrutura). Sua aplicação deve identificar esses códigos e reagendar a requisição após alguns minutos com backoff. Status dos servidores: [https://status.kobana.com.br](https://status.kobana.com.br). license: name: Proprietário — Kobana url: https://kobana.com.br servers: - url: https://api.dashboards.kobana.com.br description: Produção. Substituído em tempo de execução quando `API_V1_PUBLIC_URL` é definido. - url: https://api.dashboards.sandbox.kobana.com.br description: Sandbox — ambiente de testes isolado da produção. components: schemas: ApiV1Error: type: object properties: error: type: object properties: code: type: string description: Código de erro estável. Use este campo para tratar o erro programaticamente — nunca faça parse da `message`. example: invalid_token message: type: string description: Mensagem legível para humanos. Nunca inclui dados do usuário verbatim. example: Cabeçalho Authorization ausente. details: description: "Payload opcional específico do erro (ex.: `{ required, granted }` em `insufficient_scope`)." required: - code - message description: Envelope de erro. Presente em toda resposta 4xx e 5xx. required: - error PaginationMeta: type: object properties: total: type: integer description: Total de itens em todas as páginas. page: type: integer description: Página atual (começa em 1). per_page: type: integer description: Itens por página. total_pages: type: integer description: Total de páginas. required: - total - page - per_page - total_pages DeletedResponse: type: object properties: data: type: object properties: deleted: type: boolean example: true required: - deleted required: - data OrganizationPersonV1: type: object properties: id: type: string format: uuid name: type: string description: Razão social ou nome de exibição. nickname: type: - string - "null" legal_name: type: - string - "null" document_type: type: - string - "null" enum: - cpf - cnpj description: "Tipo de documento: `cpf` ou `cnpj`." document_number: type: - string - "null" description: Número do documento (apenas dígitos). kind: type: - string - "null" enum: - individual - company birthday: type: - string - "null" notes: type: - string - "null" addresses: description: Lista de endereços. phones: description: Lista de telefones de contato. emails: description: Lista de e-mails de contato. websites: {} tags: type: - array - "null" items: type: string custom_metadata: type: - object - "null" additionalProperties: {} metadata: type: - object - "null" additionalProperties: {} type: type: string parent_id: type: - string - "null" format: uuid external_id: type: - string - "null" created_at: type: string format: date-time updated_at: type: string format: date-time required: - name OrganizationV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Identificador público estável do recurso. external_id: type: - string - "null" description: Identificador externo da organização no sistema da Kobana. status: type: string description: "Status da organização (ex.: `active`)." created_at: type: string format: date-time updated_at: type: string format: date-time metadata: type: - object - "null" additionalProperties: {} description: Metadados arbitrários. Chaves internas (`apiKeys`, `encryptionKey`, `secrets`) são removidas antes da resposta. custom_metadata: type: - object - "null" additionalProperties: {} description: Metadados arbitrários definidos pelo cliente (chave/valor). Diferente de `metadata`, não passa por sanitização — não armazene segredos aqui. person: allOf: - $ref: "#/components/schemas/OrganizationPersonV1" - description: Dados cadastrais da organização (nome, documento, contatos, endereços). Sempre incluído. required: - id - public_id - external_id - status - created_at - updated_at - person OrganizationResponse: type: object properties: data: $ref: "#/components/schemas/OrganizationV1" required: - data OrganizationUpdateRequest: type: object properties: name: type: string minLength: 1 maxLength: 255 description: Nome de exibição da organização. email: type: string format: email description: E-mail de contato principal da organização. phone: type: string description: Telefone de contato principal da organização. addresses: type: array items: {} description: Lista de endereços da organização. custom_metadata: type: - object - "null" additionalProperties: {} description: Metadados arbitrários definidos pelo cliente (chave/valor). MeUserV1: type: - object - "null" properties: id: type: string format: uuid description: Identificador do membro do dashboard. name: type: - string - "null" description: Nome do membro. email: type: string description: E-mail do membro. required: - id - name - email description: Pessoa dona do token; `null` quando o token não pertence a uma pessoa (token de máquina). MeOrganizationV1: type: object properties: id: type: string format: uuid description: Identificador da organização à qual o token pertence. name: type: - string - "null" description: Nome de exibição da organização. external_id: type: - string - "null" description: Identificador externo da organização no sistema da Kobana. required: - id - name - external_id MeTokenV1: type: object properties: type: type: string enum: - oauth - api_key description: "`oauth` (fluxo de autorização) ou `api_key` (token pessoal ou de máquina)." scopes: type: array items: type: string description: Escopos concedidos ao token. access_level: type: string enum: - read - write - all description: "Nível de acesso mais alto concedido: `read`, `write` ou `all`." expires_at: type: - string - "null" format: date-time description: Expiração do token (ISO 8601), ou `null` quando desconhecida. required: - type - scopes - access_level - expires_at MeV1: type: object properties: user: $ref: "#/components/schemas/MeUserV1" organization: $ref: "#/components/schemas/MeOrganizationV1" token: $ref: "#/components/schemas/MeTokenV1" required: - user - organization - token MeResponse: type: object properties: data: $ref: "#/components/schemas/MeV1" required: - data PortalUserV1: type: object properties: id: type: string format: uuid public_id: type: - string - "null" format: uuid description: Identificador público da conta Kobana vinculada ao usuário, quando houver. email: type: string status: type: string enum: - active - pending_verification - pending_invitation - suspended - locked description: "`pending_invitation` (convite enviado), `pending_verification` (cadastro aguardando confirmação do e-mail), `active`, `suspended` ou `locked` (bloqueado por tentativas de login)." sso_only: type: boolean external_id: type: - string - "null" description: Identificador do usuário no seu sistema de origem (também usado no SSO). Único por workspace. tenant_id: type: - string - "null" description: "ID do titular: o identificador com que o portal casa os registros das entidades que este usuário vê. Vários usuários podem compartilhar o mesmo `tenant_id`." email_verified_at: type: - string - "null" format: date-time last_login_at: type: - string - "null" format: date-time metadata: type: - object - "null" additionalProperties: {} description: Metadados internos somente leitura, gerados pelo sistema. custom_metadata: type: - object - "null" additionalProperties: {} created_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Canal pelo qual o registro foi criado (dashboard, import, api, mcp, cli, other). Nas chamadas à API, vem do cabeçalho `X-Request-Source`. created_via_other: type: - string - "null" description: Nome do aplicativo que criou o registro quando `created_via` é `other` (cabeçalho `X-Request-Source-Other`). created_by_email: type: - string - "null" description: E-mail do usuário que criou o registro. updated_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Canal da última atualização do registro. updated_via_other: type: - string - "null" description: Nome do aplicativo da última atualização quando `updated_via` é `other` (cabeçalho `X-Request-Source-Other`). updated_by_email: type: - string - "null" description: E-mail do usuário que fez a última atualização. created_at: type: string format: date-time updated_at: type: string format: date-time name: type: - string - "null" description: Nome do perfil de contato vinculado, quando houver. required: - id - public_id - email - status - sso_only - external_id - tenant_id - email_verified_at - last_login_at - metadata - custom_metadata - created_via - created_via_other - created_by_email - updated_via - updated_via_other - updated_by_email - created_at - updated_at PortalUserListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/PortalUserV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta PortalUserResponse: type: object properties: data: $ref: "#/components/schemas/PortalUserV1" required: - data PortalUserCreateRequest: type: object properties: email: type: string description: E-mail do usuário (obrigatório). Único por workspace, sem diferenciar maiúsculas. tenant_id: type: - string - "null" description: ID do titular dos registros que o usuário verá no portal. Envie `null` para limpar. external_id: type: string description: Identificador no seu sistema externo, para idempotência/sincronização. sso_only: type: boolean description: Quando `true`, o usuário só entra pelo SSO. custom_metadata: type: - object - "null" additionalProperties: {} description: Metadados arbitrários definidos pela organização (chave/valor). required: - email PortalUserUpdateRequest: type: object properties: email: type: string description: E-mail do usuário (obrigatório). Único por workspace, sem diferenciar maiúsculas. tenant_id: type: - string - "null" description: ID do titular dos registros que o usuário verá no portal. Envie `null` para limpar. external_id: type: - string - "null" description: Identificador no seu sistema externo, para idempotência/sincronização. sso_only: type: boolean description: Quando `true`, o usuário só entra pelo SSO. status: type: string enum: - active - suspended description: "Transições permitidas: `active` ↔ `suspended`." custom_metadata: type: - object - "null" additionalProperties: {} description: Metadados arbitrários definidos pela organização (chave/valor). PortalUserEmailPreviewResponse: type: object properties: data: type: object properties: type: type: string enum: - invitation - verification from: type: string to: type: string subject: type: string message: type: string required: - type - from - to - subject - message required: - data PortalUserResendResponse: type: object properties: data: type: object properties: resent: type: boolean type: type: string enum: - invitation - verification required: - resent - type required: - data DashboardUserRoleSummary: type: object properties: id: type: string format: uuid description: UUID do papel. name: type: string description: Nome do papel. slug: type: string description: Slug (identificador estável) do papel. required: - id - name - slug DashboardUserV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Identificador público estável do recurso. organization_id: type: string format: uuid description: UUID da organização à qual o usuário pertence. person_id: type: - string - "null" format: uuid description: UUID da pessoa (registro de identidade) associada ao usuário, quando houver. external_id: type: string description: Identificador externo do usuário no Kobana OAuth. email: type: string format: email description: E-mail do usuário. name: type: - string - "null" description: Nome de exibição. picture: type: - string - "null" description: URL da foto do usuário. status: type: string enum: - active - pending_invitation - suspended description: "Status atual do usuário: `active`, `pending_invitation` ou `suspended`." permissions: type: array items: type: string description: Permissões ad-hoc atribuídas diretamente ao usuário (além das herdadas dos papéis). last_login_at: type: - string - "null" format: date-time description: Data/hora do último login. login_count: type: integer description: Quantidade total de logins realizados. show_getting_started: type: boolean description: Indica se o painel "Primeiros passos" deve ser exibido ao usuário. email_signature: type: - string - "null" description: Assinatura de e-mail configurada pelo usuário. metadata: type: - object - "null" additionalProperties: {} description: Metadados internos do sistema. custom_metadata: type: - object - "null" additionalProperties: {} description: Metadados livres definidos pelo cliente. created_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Canal pelo qual o registro foi criado (dashboard, import, api, mcp, cli, other). Nas chamadas à API, vem do cabeçalho `X-Request-Source`. created_via_other: type: - string - "null" description: Nome do aplicativo que criou o registro quando `created_via` é `other` (cabeçalho `X-Request-Source-Other`). created_by_email: type: - string - "null" description: E-mail do usuário que criou o registro. updated_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Canal da última atualização do registro. updated_via_other: type: - string - "null" description: Nome do aplicativo da última atualização quando `updated_via` é `other` (cabeçalho `X-Request-Source-Other`). updated_by_email: type: - string - "null" description: E-mail do usuário que fez a última atualização. created_at: type: string format: date-time updated_at: type: string format: date-time roles: type: array items: $ref: "#/components/schemas/DashboardUserRoleSummary" description: Papéis atribuídos ao usuário, expandidos como `{ id, name, slug }`. required: - id - public_id - organization_id - person_id - external_id - email - name - picture - status - permissions - last_login_at - login_count - show_getting_started - email_signature - metadata - custom_metadata - created_via - created_via_other - created_by_email - updated_via - updated_via_other - updated_by_email - created_at - updated_at DashboardUserListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/DashboardUserV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta DashboardUserResponse: type: object properties: data: $ref: "#/components/schemas/DashboardUserV1" required: - data DashboardUserCreateRequest: type: object properties: email: type: string format: email description: E-mail do usuário a ser convidado. name: type: string description: Nome do usuário (opcional — pode ser preenchido pelo usuário no primeiro acesso). external_id: type: string description: "Identificador externo do usuário, guardado como atributo do membro. Não define a identidade do usuário: ela é sempre resolvida pelo `email`." role_ids: type: array items: type: string format: uuid minItems: 1 description: Lista de UUIDs de papéis (`team_roles`) a atribuir ao usuário. Deve conter ao menos um item. permissions: type: array items: type: string description: Permissões ad-hoc adicionais (além das herdadas pelos papéis). Aceita os mesmos slugs de permissão. custom_metadata: type: - object - "null" additionalProperties: {} description: Metadados arbitrários definidos pelo cliente (chave/valor). required: - email - role_ids DashboardUserUpdateRequest: type: object properties: name: type: string description: Novo nome de exibição. picture: type: string description: URL da foto do usuário. status: type: string enum: - active - pending_invitation - suspended description: "Novo status: `active`, `pending_invitation` ou `suspended`." permissions: type: array items: type: string description: Lista completa de permissões ad-hoc (substitui as anteriores). role_ids: type: array items: type: string format: uuid description: Lista completa de UUIDs de papéis (substitui as atribuições atuais). external_id: type: string description: Identificador no seu sistema externo, para idempotência/sincronização. custom_metadata: type: - object - "null" additionalProperties: {} description: Metadados arbitrários definidos pelo cliente (chave/valor). TeamRoleV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Identificador público estável do recurso. organization_id: type: string format: uuid description: UUID da organização à qual o papel pertence. name: type: string description: Nome do papel. slug: type: string description: Slug estável do papel. description: type: - string - "null" description: Descrição do papel. permissions: type: array items: type: string description: Slugs de permissão concedidas pelo papel. is_system: type: boolean description: Indica se o papel é gerenciado pelo sistema (não editável/removível). is_active: type: boolean description: Indica se o papel está ativo e disponível para atribuição. display_order: type: integer description: Ordem de exibição do papel nas interfaces. metadata: type: - object - "null" additionalProperties: {} description: Metadados internos do papel. external_id: type: - string - "null" description: Identificador no seu sistema externo, para idempotência/sincronização. custom_metadata: type: - object - "null" additionalProperties: {} description: Metadados arbitrários definidos pelo cliente (chave/valor). created_at: type: string format: date-time updated_at: type: string format: date-time users_count: type: integer description: Quantidade de usuários atualmente vinculados ao papel. required: - id - public_id - organization_id - name - slug - description - permissions - is_system - is_active - display_order - metadata - external_id - custom_metadata - created_at - updated_at TeamRoleListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/TeamRoleV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta TeamRoleResponse: type: object properties: data: $ref: "#/components/schemas/TeamRoleV1" required: - data TeamRoleCreateRequest: type: object properties: name: type: string minLength: 1 description: Nome do papel (exibido na interface). slug: type: string pattern: ^[a-z][a-z0-9_]*$ description: "Slug estável usado para referenciar o papel (ex.: `support_manager`)." example: portal_manager description: type: string description: Descrição opcional do que o papel concede. permissions: type: array items: type: string description: Lista de slugs de permissão concedidas pelo papel. is_active: type: boolean description: Indica se o papel está ativo e pode ser atribuído. external_id: type: string description: Identificador no seu sistema externo, para idempotência/sincronização. custom_metadata: type: - object - "null" additionalProperties: {} description: Metadados arbitrários definidos pelo cliente (chave/valor). required: - name - slug - permissions TeamRoleUpdateRequest: type: object properties: name: type: string minLength: 1 description: Novo nome do papel. slug: type: string pattern: ^[a-z][a-z0-9_]*$ description: Novo slug do papel (mesmas regras da criação). description: type: string description: Nova descrição. permissions: type: array items: type: string description: Lista completa de permissões (substitui as anteriores). is_active: type: boolean description: Ativa ou desativa o papel. external_id: type: string description: Identificador no seu sistema externo, para idempotência/sincronização. custom_metadata: type: - object - "null" additionalProperties: {} description: Metadados arbitrários definidos pelo cliente (chave/valor). WorkspaceV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Identificador público e estável do workspace. name: type: string description: Nome do workspace. role: type: - string - "null" enum: - owner - member description: "Seu papel no workspace: `owner` (renomeia, exclui e exporta) ou `member`. `null` para um token de máquina, que age com a autoridade da organização, sem acesso concedido." max_entity_fields: type: integer description: Quantos campos uma nova entidade do workspace pode ter (definido pela Kobana). created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - public_id - name - role - max_entity_fields - created_at - updated_at WorkspaceListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/WorkspaceV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta WorkspaceResponse: type: object properties: data: $ref: "#/components/schemas/WorkspaceV1" required: - data WorkspaceWriteRequest: type: object properties: name: type: string minLength: 1 maxLength: 100 description: Nome do workspace, de 1 a 100 caracteres. required: - name WorkspaceUsageResponse: type: object properties: data: type: object properties: portal_users: type: integer description: Usuários do portal do workspace. integrations: type: integer description: Conectores (fontes de dados) do workspace. webhooks: type: integer description: Webhooks do workspace. is_empty: type: boolean description: "`true` quando não há nenhum dos itens acima." required: - portal_users - integrations - webhooks - is_empty required: - data WorkspaceExportFile: type: object properties: format: type: string description: "Formato do arquivo: `kobana-dashboards.workspace`." version: type: integer description: Versão do formato do arquivo. exported_at: type: string format: date-time required: - format - version WorkspaceImportRequest: type: object properties: data: type: object additionalProperties: {} description: O arquivo exportado, como retornado pela exportação. name: type: string maxLength: 100 description: Nome do novo workspace; por padrão, o do arquivo. required: - data WorkspaceImportWarning: type: object properties: code: type: string enum: - connector_credentials_required - oauth_secret_required - portal_domain_taken - signup_slug_taken - logos_not_copied description: "`connector_credentials_required` (conector pausado aguardando credenciais), `oauth_secret_required` (provedor OIDC sem segredo), `portal_domain_taken`, `signup_slug_taken` ou `logos_not_copied`." name: type: string description: Nome do conector ou provedor afetado. value: type: string description: Domínio ou slug que já estava em uso. required: - code WorkspaceImportResponse: type: object properties: data: $ref: "#/components/schemas/WorkspaceV1" counts: type: object properties: connectors: type: integer entities: type: integer pages: type: integer oauth_providers: type: integer required: - connectors - entities - pages - oauth_providers description: "Quanto foi criado: conectores, entidades, páginas e provedores OIDC." warnings: type: array items: $ref: "#/components/schemas/WorkspaceImportWarning" description: O que precisa ser terminado à mão. required: - data - counts - warnings WorkspaceGrantV1: type: object properties: id: type: string format: uuid description: ID do workspace. name: type: string description: Nome do workspace. granted: type: boolean description: "`true` quando o membro tem acesso ativo ao workspace." role: type: - string - "null" enum: - owner - member description: Papel do membro no workspace (`owner` ou `member`); `null` sem acesso. required: - id - name - granted - role WorkspaceGrantListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/WorkspaceGrantV1" required: - data WorkspaceGrantReplaceRequest: type: object properties: workspace_ids: type: array items: type: string format: uuid maxItems: 500 description: O conjunto final de workspaces que o membro deve acessar. Os removidos são pausados, não apagados. required: - workspace_ids DashboardUserResendResponse: type: object properties: data: type: object properties: resent: type: boolean example: true required: - resent required: - data PermissionGroupV1: type: object properties: key: type: string description: Chave do grupo (o recurso). label: type: string description: Nome do grupo para exibição. description: type: string permissions: type: array items: type: object properties: key: type: string description: Chave da permissão, como `workspaces.create`. label: type: string description: type: string required: - key - label - description required: - key - label - description - permissions PermissionCatalogResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/PermissionGroupV1" required: - data DataSourceV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid provider: type: string enum: - OPENAPI - MCP - DATABASE description: "Provedor: `OPENAPI` (API descrita por uma spec OpenAPI), `MCP` (servidor MCP) ou `DATABASE` (banco de dados somente leitura)." kind: type: string enum: - openapi - mcp - database description: "O mesmo provedor em minúsculas: `openapi`, `mcp` ou `database`." name: type: string status: type: string enum: - pending - active - error - disabled description: "`pending` (salva e ainda não testada, ou aguardando a autorização OAuth), `active`, `error` (o último teste falhou) ou `disabled`." is_active: type: boolean config: type: object additionalProperties: {} description: "Configuração da conexão sem segredos: Base URL, tipo de autenticação, arquivo da spec, transporte MCP, host do banco… Valores de query string sensíveis aparecem mascarados." credentials_set: type: array items: type: string description: Nomes dos campos secretos configurados (por exemplo `token`, `password`). Os valores nunca são devolvidos. oauth_authorized: type: boolean description: "Servidor MCP com OAuth: `true` quando já há tokens de acesso guardados." last_error: type: - string - "null" description: Mensagem do último teste de conexão que falhou; `null` quando o último deu certo. last_tested_at: type: - string - "null" format: date-time last_synced_at: type: - string - "null" format: date-time sync_cron: type: - string - "null" description: Agenda de sincronização (cron de 5 campos) no fuso `sync_timezone`; `null` para sincronizar só sob demanda. sync_timezone: type: - string - "null" operations_count: type: integer description: Quantidade de operações da fonte (endpoints, tools ou tabelas). created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - public_id - provider - kind - name - status - is_active - config - credentials_set - oauth_authorized - last_error - last_tested_at - last_synced_at - sync_cron - sync_timezone - created_at - updated_at DataSourceOperationV1: type: object properties: id: type: string format: uuid key: type: string description: "Chave estável da operação: `operationId` (ou método + caminho) na OpenAPI, nome da tool no MCP, tabela/coleção no banco." kind: type: string enum: - list - retrieve - create - update - delete - action access: type: string enum: - read - write description: "`read` (pode alimentar entidades) ou `write`." name: type: string description: type: - string - "null" method: type: - string - "null" path: type: - string - "null" external_object: type: - string - "null" description: Objeto externo que a operação devolve (por exemplo `customer`), quando identificado. tags: type: array items: type: string input_schema: description: Parâmetros aceitos pela operação (JSON Schema). output_schema: description: Formato da resposta (JSON Schema), quando conhecido. fields: description: Campos dos registros devolvidos, com caminho e tipo. records_path: type: - string - "null" description: Caminho, na resposta, da lista de registros. pagination: description: Como a operação pagina (página, offset, cursor), quando detectado. incremental: description: Parâmetro de leitura incremental (por exemplo `updated_since`), quando detectado. enabled: type: boolean description: Operações desligadas não alimentam entidades. deprecated: type: boolean position: type: integer created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - key - kind - access - name - description - method - path - external_object - tags - records_path - enabled - deprecated - position - created_at - updated_at DataSourceDetailV1: allOf: - $ref: "#/components/schemas/DataSourceV1" - type: object properties: operations: type: array items: $ref: "#/components/schemas/DataSourceOperationV1" description: Operações da fonte, na ordem de `position`. required: - operations DataSourceConnectionTestV1: type: object properties: success: type: boolean message: type: string description: Resumo do resultado, em português, pronto para exibir. http_status: type: integer duration_ms: type: integer operation_key: type: - string - "null" description: "OpenAPI: operação usada como sonda do teste." records_found: type: - integer - "null" tools_count: type: integer description: "MCP: tools listadas pelo servidor." requires_authorization: type: boolean description: "MCP: o servidor exige autorização OAuth antes de qualquer chamada." objects_count: type: integer description: "Banco de dados: tabelas, views e coleções encontradas." required: - success - message DataSourceRequestLogSummaryV1: type: object properties: id: type: string format: uuid service: type: string method: type: string endpoint: type: string description: URL chamada (valores sensíveis mascarados) ou a consulta ao banco. http_status: type: - integer - "null" success: type: boolean error_message: type: - string - "null" duration_ms: type: - integer - "null" created_at: type: string format: date-time required: - id - service - method - endpoint - http_status - success - error_message - duration_ms - created_at DataSourceRequestLogV1: type: object properties: id: type: string format: uuid service: type: string method: type: string endpoint: type: string description: URL chamada (valores sensíveis mascarados) ou a consulta ao banco. http_status: type: - integer - "null" success: type: boolean error_message: type: - string - "null" duration_ms: type: - integer - "null" created_at: type: string format: date-time request_headers: description: Cabeçalhos HTTP, com segredos mascarados. request_body: type: - string - "null" response_headers: description: Cabeçalhos HTTP, com segredos mascarados. response_body: type: - string - "null" required: - id - service - method - endpoint - http_status - success - error_message - duration_ms - created_at - request_body - response_body DataSourceCatalogProductV1: type: object properties: key: type: string description: Chave do produto, usada em `product` ao conectar. name: type: string description: type: string docs_url: type: string token_help: type: string description: Onde obter o token de API do produto. base_urls: type: object additionalProperties: type: string description: Base URL por ambiente (`production`, `sandbox`). workspace_header: type: - string - "null" description: Cabeçalho com que o produto escolhe um workspace dentro da organização do token, quando há. required: - key - name - description - docs_url - token_help - base_urls - workspace_header DataSourceSpecAnalysisV1: type: object properties: format: type: string enum: - json - yaml spec_version: type: string title: type: string api_version: type: - string - "null" description: type: - string - "null" servers: type: array items: type: string security_schemes: type: array items: type: object additionalProperties: {} suggested_auth: type: object additionalProperties: {} description: Autenticação que a spec declara, já no formato do campo `auth`. suggested_response_format: type: string enum: - json - xml warnings: type: array items: type: string operations_count: type: integer operations: type: array items: type: object properties: key: type: string name: type: string kind: type: string enum: - list - retrieve - create - update - delete - action access: type: string enum: - read - write method: type: - string - "null" path: type: - string - "null" external_object: type: - string - "null" records_path: type: - string - "null" pagination: {} incremental: {} fields_count: type: integer deprecated: type: boolean required: - key - name - kind - access - method - path - external_object - records_path - fields_count - deprecated required: - format - spec_version - title - api_version - description - servers - security_schemes - suggested_auth - suggested_response_format - warnings - operations_count - operations DataSourceOpenApiCreateRequest: type: object properties: spec: type: string description: O documento OpenAPI 3.x ou Swagger 2.0 como texto (JSON ou YAML), até 5 MB — limitado também pelos 2 MB de corpo da API. spec_file_name: type: string description: Nome do arquivo da spec (`openapi.yaml`). Quando omitido, é deduzido do conteúdo. certificate: type: object properties: filename: type: string description: "Nome original do arquivo: .pfx, .p12, .pem, .crt ou .cer." content_base64: type: string description: O arquivo em base64 (até 64 KB depois de decodificado). required: - filename - content_base64 description: Certificado de cliente para mTLS (`auth.kind = "cert"`). name: type: string description: Nome de exibição, único por workspace e tipo. Quando omitido, é derivado da spec, do host ou do banco. base_url: type: string description: Base URL da API. Quando omitida, usa o primeiro servidor absoluto da spec. auth: type: object properties: kind: type: string enum: - none - header - query - bearer - basic - cert headers: type: array items: type: object properties: name: type: string value: type: - string - "null" required: - name params: type: array items: type: object properties: name: type: string value: type: - string - "null" required: - name required: - kind description: "Como a API autentica: `none`, `header`, `query`, `bearer`, `basic` ou `cert`. Em `header`/`query`, informe os nomes e valores das chaves; um valor em branco numa atualização mantém o guardado." credentials: type: object properties: token: type: string username: type: string password: type: string certificate_password: type: string description: "Segredos da autenticação escolhida: `token` (bearer), `username`/`password` (basic), `certificate_password` (cert). Guardados criptografados e nunca devolvidos." response_format: type: string enum: - json - xml required: - spec DataSourceMcpCreateRequest: type: object properties: name: type: string description: Nome de exibição, único por workspace e tipo. Quando omitido, é derivado da spec, do host ou do banco. url: type: string description: URL do servidor MCP (endpoint Streamable HTTP ou SSE). Um token na query string é guardado criptografado. transport: type: string enum: - http - sse headers: anyOf: - type: string - type: object additionalProperties: type: string description: "Cabeçalhos extras enviados em toda chamada: um objeto, ou um `Nome: valor` por linha. Guardados criptografados." oauth: type: object properties: mode: type: string enum: - none - dcr - client client_id: type: - string - "null" client_secret: type: - string - "null" scopes: type: - string - "null" required: - mode description: "OAuth do servidor MCP: `none`, `dcr` (registro dinâmico de cliente) ou `client` (seu próprio client id/secret)." required: - url DataSourceDatabaseCreateRequest: type: object properties: engine: type: string enum: - postgres - mysql - mariadb - mssql - mongodb name: type: string description: Nome de exibição, único por workspace e tipo. Quando omitido, é derivado da spec, do host ou do banco. host: type: - string - "null" port: anyOf: - type: integer - type: string - type: "null" database: type: - string - "null" username: type: - string - "null" password: type: - string - "null" connection_string: type: - string - "null" description: "Somente MongoDB: a string de conexão completa (no lugar de host, porta, usuário e senha). Autenticação só por usuário e senha (SCRAM); opções aceitas: authSource, authMechanism (SCRAM-SHA-1/SCRAM-SHA-256), replicaSet, tls/ssl, retryWrites, retryReads, w, journal, wtimeoutMS, readPreference, readConcernLevel, appName, directConnection, loadBalanced, compressors, zlibCompressionLevel e os tempos/limites de pool (maxPoolSize, minPoolSize, maxIdleTimeMS, connectTimeoutMS, socketTimeoutMS, serverSelectionTimeoutMS, heartbeatFrequencyMS, localThresholdMS, maxStalenessSeconds). Qualquer outra opção é recusada com 422." ssl: type: boolean ssl_verify: type: boolean required: - engine DataSourceCatalogConnectRequest: type: object properties: product: type: string description: Chave do produto do catálogo Kobana (veja `GET /data_sources/catalog`). environment: type: string enum: - production - sandbox token: type: string description: Token de API do produto. Guardado criptografado. workspace_id: type: - string - "null" description: Workspace dentro do produto, quando a organização do token tem mais de um. name: type: string description: Nome de exibição, único por workspace e tipo. Quando omitido, é derivado da spec, do host ou do banco. required: - product DataSourceSpecRequest: type: object properties: spec: type: string description: O documento OpenAPI 3.x ou Swagger 2.0 como texto (JSON ou YAML), até 5 MB — limitado também pelos 2 MB de corpo da API. spec_file_name: type: string description: Nome do arquivo da spec (`openapi.yaml`). Quando omitido, é deduzido do conteúdo. required: - spec DataSourceDraftTestRequest: anyOf: - type: object properties: kind: type: string enum: - openapi spec: type: string description: O documento OpenAPI 3.x ou Swagger 2.0 como texto (JSON ou YAML), até 5 MB — limitado também pelos 2 MB de corpo da API. spec_file_name: type: string description: Nome do arquivo da spec (`openapi.yaml`). Quando omitido, é deduzido do conteúdo. certificate: type: object properties: filename: type: string description: "Nome original do arquivo: .pfx, .p12, .pem, .crt ou .cer." content_base64: type: string description: O arquivo em base64 (até 64 KB depois de decodificado). required: - filename - content_base64 description: Certificado de cliente para mTLS (`auth.kind = "cert"`). name: type: string description: Nome de exibição, único por workspace e tipo. Quando omitido, é derivado da spec, do host ou do banco. base_url: type: string description: Base URL da API. Quando omitida, usa o primeiro servidor absoluto da spec. auth: type: object properties: kind: type: string enum: - none - header - query - bearer - basic - cert headers: type: array items: type: object properties: name: type: string value: type: - string - "null" required: - name params: type: array items: type: object properties: name: type: string value: type: - string - "null" required: - name required: - kind description: "Como a API autentica: `none`, `header`, `query`, `bearer`, `basic` ou `cert`. Em `header`/`query`, informe os nomes e valores das chaves; um valor em branco numa atualização mantém o guardado." credentials: type: object properties: token: type: string username: type: string password: type: string certificate_password: type: string description: "Segredos da autenticação escolhida: `token` (bearer), `username`/`password` (basic), `certificate_password` (cert). Guardados criptografados e nunca devolvidos." response_format: type: string enum: - json - xml required: - kind - spec - type: object properties: kind: type: string enum: - mcp name: type: string description: Nome de exibição, único por workspace e tipo. Quando omitido, é derivado da spec, do host ou do banco. url: type: string description: URL do servidor MCP (endpoint Streamable HTTP ou SSE). Um token na query string é guardado criptografado. transport: type: string enum: - http - sse headers: anyOf: - type: string - type: object additionalProperties: type: string description: "Cabeçalhos extras enviados em toda chamada: um objeto, ou um `Nome: valor` por linha. Guardados criptografados." oauth: type: object properties: mode: type: string enum: - none - dcr - client client_id: type: - string - "null" client_secret: type: - string - "null" scopes: type: - string - "null" required: - mode description: "OAuth do servidor MCP: `none`, `dcr` (registro dinâmico de cliente) ou `client` (seu próprio client id/secret)." required: - kind - url - type: object properties: kind: type: string enum: - database engine: type: string enum: - postgres - mysql - mariadb - mssql - mongodb name: type: string description: Nome de exibição, único por workspace e tipo. Quando omitido, é derivado da spec, do host ou do banco. host: type: - string - "null" port: anyOf: - type: integer - type: string - type: "null" database: type: - string - "null" username: type: - string - "null" password: type: - string - "null" connection_string: type: - string - "null" description: "Somente MongoDB: a string de conexão completa (no lugar de host, porta, usuário e senha). Autenticação só por usuário e senha (SCRAM); opções aceitas: authSource, authMechanism (SCRAM-SHA-1/SCRAM-SHA-256), replicaSet, tls/ssl, retryWrites, retryReads, w, journal, wtimeoutMS, readPreference, readConcernLevel, appName, directConnection, loadBalanced, compressors, zlibCompressionLevel e os tempos/limites de pool (maxPoolSize, minPoolSize, maxIdleTimeMS, connectTimeoutMS, socketTimeoutMS, serverSelectionTimeoutMS, heartbeatFrequencyMS, localThresholdMS, maxStalenessSeconds). Qualquer outra opção é recusada com 422." ssl: type: boolean ssl_verify: type: boolean required: - kind - engine - type: object properties: kind: type: string enum: - catalog product: type: string description: Chave do produto do catálogo Kobana (veja `GET /data_sources/catalog`). environment: type: string enum: - production - sandbox token: type: string description: Token de API do produto. Guardado criptografado. workspace_id: type: - string - "null" description: Workspace dentro do produto, quando a organização do token tem mais de um. name: type: string description: Nome de exibição, único por workspace e tipo. Quando omitido, é derivado da spec, do host ou do banco. required: - kind - product description: Informe `kind` e o corpo da rota de criação correspondente. Nada é salvo. DataSourceUpdateRequest: type: object properties: name: type: string description: Nome de exibição, único por workspace e tipo. Quando omitido, é derivado da spec, do host ou do banco. is_active: type: boolean base_url: type: string description: Base URL da API. Quando omitida, usa o primeiro servidor absoluto da spec. auth: type: object properties: kind: type: string enum: - none - header - query - bearer - basic - cert headers: type: array items: type: object properties: name: type: string value: type: - string - "null" required: - name params: type: array items: type: object properties: name: type: string value: type: - string - "null" required: - name required: - kind description: "Como a API autentica: `none`, `header`, `query`, `bearer`, `basic` ou `cert`. Em `header`/`query`, informe os nomes e valores das chaves; um valor em branco numa atualização mantém o guardado." credentials: type: object properties: token: type: string username: type: string password: type: string certificate_password: type: string description: "Segredos da autenticação escolhida: `token` (bearer), `username`/`password` (basic), `certificate_password` (cert). Guardados criptografados e nunca devolvidos." certificate: type: object properties: filename: type: string description: "Nome original do arquivo: .pfx, .p12, .pem, .crt ou .cer." content_base64: type: string description: O arquivo em base64 (até 64 KB depois de decodificado). required: - filename - content_base64 description: Certificado de cliente para mTLS (`auth.kind = "cert"`). probe_operation_key: type: - string - "null" description: "OpenAPI: operação usada como sonda no teste de conexão; `null` escolhe automaticamente." default_params: type: object additionalProperties: type: string description: "OpenAPI: valores padrão de parâmetros enviados em toda chamada." response_format: type: string enum: - json - xml url: type: string description: URL do servidor MCP (endpoint Streamable HTTP ou SSE). Um token na query string é guardado criptografado. transport: type: string enum: - http - sse headers: anyOf: - type: string - type: object additionalProperties: type: string description: "Cabeçalhos extras enviados em toda chamada: um objeto, ou um `Nome: valor` por linha. Guardados criptografados." oauth: type: object properties: mode: type: string enum: - none - dcr - client client_id: type: - string - "null" client_secret: type: - string - "null" scopes: type: - string - "null" required: - mode description: "OAuth do servidor MCP: `none`, `dcr` (registro dinâmico de cliente) ou `client` (seu próprio client id/secret)." engine: type: string enum: - postgres - mysql - mariadb - mssql - mongodb host: type: - string - "null" port: anyOf: - type: integer - type: string - type: "null" database: type: - string - "null" username: type: - string - "null" password: type: - string - "null" connection_string: type: - string - "null" description: "Somente MongoDB: a string de conexão completa (no lugar de host, porta, usuário e senha). Autenticação só por usuário e senha (SCRAM); opções aceitas: authSource, authMechanism (SCRAM-SHA-1/SCRAM-SHA-256), replicaSet, tls/ssl, retryWrites, retryReads, w, journal, wtimeoutMS, readPreference, readConcernLevel, appName, directConnection, loadBalanced, compressors, zlibCompressionLevel e os tempos/limites de pool (maxPoolSize, minPoolSize, maxIdleTimeMS, connectTimeoutMS, socketTimeoutMS, serverSelectionTimeoutMS, heartbeatFrequencyMS, localThresholdMS, maxStalenessSeconds). Qualquer outra opção é recusada com 422." ssl: type: boolean ssl_verify: type: boolean description: Campos aceitos conforme o tipo da fonte (OpenAPI, MCP ou banco); os de outro tipo são ignorados. Campos secretos em branco mantêm os guardados. DataSourceScheduleRequest: type: object properties: cron: type: - string - "null" description: Cron de 5 campos (no máximo a cada 5 minutos), ou `null` para sincronizar só sob demanda. timezone: type: - string - "null" description: "Fuso horário IANA da agenda. Padrão: o atual da fonte, ou America/Sao_Paulo." required: - cron DataSourceSyncRequest: type: object properties: full: type: boolean description: "`true` relê tudo em vez de só o que mudou desde a última sincronização." DataSourceOperationUpdateRequest: type: object properties: enabled: type: boolean description: Operações desligadas não alimentam entidades. required: - enabled DataSourceListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/DataSourceV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta DataSourceRequestLogListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/DataSourceRequestLogSummaryV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta DataSourceResponse: type: object properties: data: $ref: "#/components/schemas/DataSourceV1" required: - data DataSourceDetailResponse: type: object properties: data: $ref: "#/components/schemas/DataSourceDetailV1" required: - data DataSourceOperationResponse: type: object properties: data: $ref: "#/components/schemas/DataSourceOperationV1" required: - data DataSourceRequestLogResponse: type: object properties: data: $ref: "#/components/schemas/DataSourceRequestLogV1" required: - data DataSourceCatalogResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/DataSourceCatalogProductV1" required: - data DataSourceSpecAnalysisResponse: type: object properties: data: $ref: "#/components/schemas/DataSourceSpecAnalysisV1" required: - data DataSourceCreatedResponse: type: object properties: data: type: object properties: data_source: $ref: "#/components/schemas/DataSourceV1" test: allOf: - $ref: "#/components/schemas/DataSourceConnectionTestV1" - type: - object - "null" required: - data_source - test required: - data DataSourceMcpCreatedResponse: type: object properties: data: type: object properties: data_source: $ref: "#/components/schemas/DataSourceV1" test: allOf: - $ref: "#/components/schemas/DataSourceConnectionTestV1" - type: - object - "null" authorization_url: type: - string - "null" description: Página de autorização OAuth do servidor MCP. Uma pessoa logada no dashboard precisa abri-la no navegador para concluir a conexão; `null` quando não há nada a autorizar. required: - data_source - test - authorization_url required: - data DataSourceDraftTestResponse: type: object properties: data: type: object properties: test: $ref: "#/components/schemas/DataSourceConnectionTestV1" operations_count: type: integer description: "OpenAPI: operações que a spec importaria." required: - test required: - data DataSourceTestResponse: type: object properties: data: type: object properties: test: $ref: "#/components/schemas/DataSourceConnectionTestV1" data_source: $ref: "#/components/schemas/DataSourceV1" required: - test - data_source required: - data DataSourceSyncResponse: type: object properties: data: type: object properties: sync_id: type: string format: uuid description: ID da execução de sincronização. required: - sync_id required: - data DataSourceScheduleResponse: type: object properties: data: type: object properties: data_source: $ref: "#/components/schemas/DataSourceV1" next_runs: type: array items: type: string format: date-time description: Próximas cinco execuções (UTC); vazio quando só sob demanda. required: - data_source - next_runs required: - data DataSourceSpecResponse: type: object properties: data: type: object properties: data_source: $ref: "#/components/schemas/DataSourceV1" warnings: type: array items: type: string required: - data_source - warnings required: - data DataSourceAuthorizeResponse: type: object properties: data: type: object properties: authorization_url: type: - string - "null" description: Página de autorização OAuth do servidor MCP. Uma pessoa logada no dashboard precisa abri-la no navegador para concluir a conexão; `null` quando não há nada a autorizar. test: allOf: - $ref: "#/components/schemas/DataSourceConnectionTestV1" - type: - object - "null" required: - authorization_url - test required: - data EntityPaginationV1: type: object properties: style: type: string enum: - none - page - offset - cursor description: Estilo de paginação; os demais campos dependem dele. page_param: type: string offset_param: type: string cursor_param: type: string size_param: type: string limit_param: type: string next_cursor_path: type: string page_size: type: integer description: Registros por página pedidos à origem; ausente = o padrão da sincronização. required: - style description: "Como a sincronização pagina a origem: `none`, `page` (`page_param`, `size_param`), `offset` (`offset_param`, `limit_param`) ou `cursor` (`cursor_param`, `size_param`, `next_cursor_path`)." EntitySyncFilterV1: type: object properties: target: type: string description: Parâmetro da operação (ou coluna da tabela) que recebe o filtro. op: type: string enum: - eq - neq - gt - gte - lt - lte - contains - starts_with - in - is_null - not_null value: description: 'Valor do filtro: texto, número, booleano, lista, `null` ou uma data relativa `{ "relative_days": -30 }`.' required: - target - op EntityJoinSpecV1: type: object properties: base_entity_id: type: string format: uuid description: "Entidade base: todos os seus registros entram na relação." related_entity_id: type: string format: uuid description: Entidade relacionada, casada com a base pelos campos informados. base_field: type: string description: Chave do campo da entidade base usado no casamento. related_field: type: string description: Chave do campo da entidade relacionada usado no casamento. type: type: string enum: - inner - left description: "`left` (padrão) mantém os registros da base sem par; `inner` só os que casam." match: type: string enum: - exact - digits description: "`exact` (padrão) compara o texto; `digits` compara só os dígitos (CPF com e sem pontuação casam)." required: - base_entity_id - related_entity_id - base_field - related_field EntityFieldV1: type: object properties: id: type: string format: uuid key: type: string name: type: string data_type: type: string enum: - string - int - decimal - money - bool - date - datetime - email - enum - document - phone - url - file - array - json semantic_role: type: - string - "null" enum: - identifier - reference - label - status - due_date - amount - created_at - updated_at - email - document - phone - url description: "Papel do campo: identificador, referência, título, valor monetário, status, data…" source_path: type: string description: Caminho do valor no registro da origem; vazio em um campo calculado. expression: type: - string - "null" description: "Campo calculado: template sobre os outros campos, como `P-{{ $resource.numero }}`; `null` em um campo lido da origem." format: type: - string - "null" enum_options: type: - array - "null" items: {} visible: type: boolean filterable: type: boolean sortable: type: boolean position: type: integer required: - id - key - name - data_type - semantic_role - source_path - expression - format - enum_options - visible - filterable - sortable - position EntitySourceV1: type: object properties: integration_id: type: string format: uuid description: Fonte de dados (conector) de onde a entidade lê. integration_name: type: string kind: type: string enum: - openapi - mcp - database description: "Tipo da fonte de dados: `openapi`, `mcp` ou `database`." source_kind: type: string enum: - operation - sql - join description: "`operation` (endpoint, tool ou tabela), `sql` (consulta em banco SQL) ou `join` (relação entre duas entidades)." join: allOf: - $ref: "#/components/schemas/EntityJoinSpecV1" - type: - object - "null" description: "Em uma entidade `join`: as duas entidades, os campos que casam e como; `null` nas demais." operation_id: type: - string - "null" format: uuid operation_key: type: - string - "null" operation_name: type: - string - "null" method: type: - string - "null" path: type: - string - "null" sql: type: - string - "null" params: type: - object - "null" additionalProperties: {} description: Parâmetros com que a operação é chamada. records_path: type: - string - "null" pagination: allOf: - $ref: "#/components/schemas/EntityPaginationV1" - type: - object - "null" description: Paginação da sincronização; `null` = a detectada na operação (`operation_pagination`). operation_pagination: type: - object - "null" additionalProperties: {} sync_filters: type: array items: $ref: "#/components/schemas/EntitySyncFilterV1" required: - integration_id - integration_name - kind - source_kind - join - operation_id - operation_key - operation_name - method - path - sql - params - records_path - pagination - operation_pagination - sync_filters EntityV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid key: type: string description: Nome de máquina que os blocos do portal usam; único no workspace (até 63 caracteres). name: type: string name_plural: type: string description: type: - string - "null" source: $ref: "#/components/schemas/EntitySourceV1" sync_mode: type: string enum: - scheduled - manual - on_access description: "Quando a sincronização roda: `scheduled` (agendada), `manual` ou `on_access` (os registros de cada titular são lidos quando um usuário dele abre o portal)." freshness_seconds: type: integer description: "`on_access`: por quantos segundos os registros sincronizados de um titular valem como atuais." identifier_field_key: type: - string - "null" label_field_key: type: - string - "null" owner_field_key: type: - string - "null" description: Campo com o ID do titular, casado com o `tenant_id` do usuário do portal. Sem ele a entidade não aparece no portal. owner_match: type: string enum: - external_id - document_number description: "Como o campo do titular é comparado com o `tenant_id`: como texto (`external_id`) ou como CPF/CNPJ (`document_number`, só dígitos)." fields: type: array items: $ref: "#/components/schemas/EntityFieldV1" sampled_at: type: - string - "null" format: date-time sample: type: array items: type: object additionalProperties: {} description: Alguns registros como a origem os devolveu, guardados para reinferir campos. sync: type: - object - "null" properties: status: type: - string - "null" error: type: - string - "null" last_synced_at: type: - string - "null" format: date-time records_count: type: integer required: - status - error - last_synced_at - records_count description: Onde está a cópia dos registros; `null` antes da primeira sincronização. created_by_email: type: - string - "null" created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - public_id - key - name - name_plural - description - source - sync_mode - freshness_seconds - identifier_field_key - label_field_key - owner_field_key - owner_match - fields - sampled_at - sample - sync - created_by_email - created_at - updated_at EntityResponse: type: object properties: data: $ref: "#/components/schemas/EntityV1" required: - data EntityListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/EntityV1" required: - data EntityRecordV1: type: object properties: id: type: string format: uuid external_id: type: string description: Valor do campo identificador, ou um hash do registro quando a entidade não tem um. owner_id: type: - string - "null" description: Valor do campo do titular, casado com o `tenant_id` dos usuários do portal. data: type: object additionalProperties: {} description: Valores do registro por chave de campo — o que blocos, filtros e ordenações leem. raw: type: object additionalProperties: {} description: O registro como a origem o devolveu. source_updated_at: type: - string - "null" format: date-time synced_at: type: string format: date-time created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - external_id - owner_id - data - raw - source_updated_at - synced_at - created_at - updated_at EntityRecordResponse: type: object properties: data: type: object properties: entity: $ref: "#/components/schemas/EntityV1" record: $ref: "#/components/schemas/EntityRecordV1" required: - entity - record required: - data EntityTenantSyncInfoV1: type: object properties: status: type: string enum: - fresh - refreshing - syncing - error last_synced_at: type: - string - "null" format: date-time error: type: - string - "null" required: - status - last_synced_at - error description: "Com `preview_as` em uma entidade `on_access`: onde está a sincronização daquele titular." EntityRecordsQueryResponse: type: object properties: data: type: object properties: records: type: array items: type: object additionalProperties: {} description: "Valores de cada registro por chave de campo, mais `_record: { id, external_id }`." total: type: integer limit: type: integer offset: type: integer fields: type: array items: type: object properties: key: type: string name: type: string data_type: type: string semantic_role: type: - string - "null" required: - key - name - data_type - semantic_role synced_at: type: - string - "null" format: date-time sync: allOf: - $ref: "#/components/schemas/EntityTenantSyncInfoV1" - type: - object - "null" required: - records - total - limit - offset - fields - synced_at required: - data EntityRecordsClearedResponse: type: object properties: data: type: object properties: cleared: type: integer description: Quantos registros foram removidos. required: - cleared required: - data EntityAggregateResponse: type: object properties: data: type: object properties: value: anyOf: - type: number - type: string - type: "null" description: Resultado da agregação, sem `group_by`. groups: type: array items: type: object properties: key: {} value: anyOf: - type: number - type: string - type: "null" required: - value description: "Com `group_by`: um resultado por valor do campo (até 100 grupos)." sync: allOf: - $ref: "#/components/schemas/EntityTenantSyncInfoV1" - type: - object - "null" required: - data EntityUsageResponse: type: object properties: data: type: object properties: pages: type: array items: type: object properties: page_id: type: string name: type: string path: type: string blocks: type: array items: type: string description: Tipos dos blocos da página que leem a entidade, um por bloco. in_draft: type: boolean in_published: type: boolean required: - page_id - name - path - blocks - in_draft - in_published required: - pages required: - data EntityPreviewResponse: type: object properties: data: type: object properties: source: type: object properties: integration_id: type: string format: uuid integration_name: type: string kind: type: string enum: - openapi - mcp - database source_kind: type: string enum: - operation - sql operation_id: type: - string - "null" format: uuid operation_key: type: - string - "null" operation_name: type: string sql: type: - string - "null" records_path: type: - string - "null" required: - integration_id - integration_name - kind - source_kind - operation_id - operation_key - operation_name - sql - records_path max_fields: type: integer description: Quantos campos o workspace permite que a nova entidade mantenha. records: type: array items: type: object additionalProperties: {} description: A amostra de registros devolvida pela origem. entity: type: object properties: key: type: string name: type: string name_plural: type: string fields: type: array items: type: object additionalProperties: {} identifier_field_key: type: - string - "null" label_field_key: type: - string - "null" owner_field_key: type: - string - "null" required: - key - name - name_plural - fields - identifier_field_key - label_field_key - owner_field_key description: "A entidade proposta a partir da amostra: chave, nomes, campos e campos especiais." duration_ms: type: integer required: - source - max_fields - records - entity - duration_ms required: - data EntityJoinPreviewResponse: type: object properties: data: type: object properties: base: type: object properties: id: type: string format: uuid key: type: string name: type: string identifier_field_key: type: - string - "null" label_field_key: type: - string - "null" owner_field_key: type: - string - "null" fields: type: array items: type: object additionalProperties: {} required: - id - key - name - identifier_field_key - label_field_key - owner_field_key - fields related: type: object properties: id: type: string format: uuid key: type: string name: type: string identifier_field_key: type: - string - "null" label_field_key: type: - string - "null" owner_field_key: type: - string - "null" fields: type: array items: type: object additionalProperties: {} required: - id - key - name - identifier_field_key - label_field_key - owner_field_key - fields stats: type: object additionalProperties: {} description: "Contagens do casamento: registros da base, com par, sem par." sample: type: array items: type: object additionalProperties: {} description: "As primeiras linhas combinadas: `{ _id, base: {...}, related: {...} | null }`." required: - base - related - stats - sample required: - data EntitySyncQueuedResponse: type: object properties: data: type: object properties: sync_id: type: string format: uuid description: ID da sincronização enfileirada. required: - sync_id required: - data EntitySyncStateResponse: type: object properties: data: type: - object - "null" properties: status: type: - string - "null" description: Status da última sincronização (`queued`, `running`, `completed`, `error`…). error: type: - string - "null" last_synced_at: type: - string - "null" format: date-time last_full_sync_at: type: - string - "null" format: date-time records_count: type: integer stats: type: - object - "null" additionalProperties: {} required: - status - error - last_synced_at - last_full_sync_at - records_count - stats description: Onde está a sincronização da entidade; `null` antes da primeira. required: - data EntityTenantSyncV1: type: object properties: tenant_id: type: string users: type: object properties: count: type: integer emails: type: array items: type: string required: - count - emails description: "Usuários do portal com esse Tenant ID: quantos e os primeiros e-mails." status: type: - string - "null" error: type: - string - "null" last_synced_at: type: - string - "null" format: date-time last_full_sync_at: type: - string - "null" format: date-time last_accessed_at: type: - string - "null" format: date-time records_count: type: integer stats: type: object additionalProperties: {} required: - tenant_id - users - status - error - last_synced_at - last_full_sync_at - last_accessed_at - records_count - stats EntityTenantSyncListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/EntityTenantSyncV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta EntityTenantSyncQueuedResponse: type: object properties: data: type: object properties: status: type: string enum: - queued required: - status required: - data EntitySyncLogSummaryV1: type: object properties: id: type: string format: uuid service: type: string method: type: string endpoint: type: string http_status: type: - integer - "null" success: type: boolean error_message: type: - string - "null" duration_ms: type: - integer - "null" created_at: type: string format: date-time required: - id - service - method - endpoint - http_status - success - error_message - duration_ms - created_at EntitySyncLogListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/EntitySyncLogSummaryV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta EntitySyncLogV1: type: object properties: id: type: string format: uuid service: type: string method: type: string endpoint: type: string http_status: type: - integer - "null" success: type: boolean error_message: type: - string - "null" duration_ms: type: - integer - "null" created_at: type: string format: date-time request_headers: type: - object - "null" additionalProperties: {} request_body: type: - string - "null" response_headers: type: - object - "null" additionalProperties: {} response_body: type: - string - "null" required: - id - service - method - endpoint - http_status - success - error_message - duration_ms - created_at - request_headers - request_body - response_headers - response_body description: "Uma chamada da sincronização inteira: o que foi enviado e o que voltou (segredos mascarados ao gravar)." EntitySyncLogResponse: type: object properties: data: $ref: "#/components/schemas/EntitySyncLogV1" required: - data EntityFieldInputV1: type: object properties: key: type: string maxLength: 63 name: type: string maxLength: 200 data_type: type: string enum: - string - int - decimal - money - bool - date - datetime - email - enum - document - phone - url - file - array - json semantic_role: type: - string - "null" enum: - identifier - reference - label - status - due_date - amount - created_at - updated_at - email - document - phone - url source_path: type: string maxLength: 500 description: Caminho do valor no registro da origem; vazio em um campo calculado. expression: type: - string - "null" maxLength: 4000 description: "Campo calculado: template sobre os outros campos, como `P-{{ $resource.numero }}`; `null` em um campo lido da origem." format: type: - string - "null" maxLength: 100 enum_options: type: - array - "null" items: {} maxItems: 200 visible: type: boolean description: Se o campo aparece nos blocos do portal (padrão `true`). filterable: type: boolean sortable: type: boolean required: - key - name - data_type EntityPreviewRequest: type: object properties: integration_id: type: string format: uuid description: Fonte de dados (conector) de onde ler. operation_id: type: string format: uuid description: Operação de leitura (endpoint, tool ou tabela) da fonte. Envie este campo ou `sql`, não os dois. sql: type: string maxLength: 20000 description: Consulta SQL em uma fonte de banco SQL. Envie este campo ou `operation_id`. params: type: object additionalProperties: {} description: Parâmetros com que a operação é chamada (padrão `{}`). pagination: allOf: - $ref: "#/components/schemas/EntityPaginationV1" - type: - object - "null" description: Paginação da sincronização; `null` = a detectada na operação (`operation_pagination`). sync_filters: type: array items: $ref: "#/components/schemas/EntitySyncFilterV1" maxItems: 20 description: O que a sincronização envia para filtrar os registros (até 20). Ignorado em uma consulta SQL. limit: type: integer minimum: 1 maximum: 50 description: Tamanho da amostra (padrão 10, máximo 50). required: - integration_id EntityCreateRequest: type: object properties: integration_id: type: string format: uuid description: Fonte de dados (conector) de onde ler. operation_id: type: string format: uuid description: Operação de leitura (endpoint, tool ou tabela) da fonte. Envie este campo ou `sql`, não os dois. sql: type: string maxLength: 20000 description: Consulta SQL em uma fonte de banco SQL. Envie este campo ou `operation_id`. params: type: object additionalProperties: {} description: Parâmetros com que a operação é chamada (padrão `{}`). pagination: allOf: - $ref: "#/components/schemas/EntityPaginationV1" - type: - object - "null" description: Paginação da sincronização; `null` = a detectada na operação (`operation_pagination`). sync_filters: type: array items: $ref: "#/components/schemas/EntitySyncFilterV1" maxItems: 20 description: O que a sincronização envia para filtrar os registros (até 20). Ignorado em uma consulta SQL. key: type: string maxLength: 63 description: Nome de máquina que os blocos do portal usam; único no workspace (até 63 caracteres). name: type: string maxLength: 200 name_plural: type: string maxLength: 200 description: type: - string - "null" maxLength: 2000 identifier_field_key: type: - string - "null" maxLength: 63 label_field_key: type: - string - "null" maxLength: 63 owner_field_key: type: - string - "null" maxLength: 63 description: Campo com o ID do titular, casado com o `tenant_id` do usuário do portal. Sem ele a entidade não aparece no portal. owner_match: type: string enum: - external_id - document_number description: "Como o campo do titular é comparado com o `tenant_id`: como texto (`external_id`) ou como CPF/CNPJ (`document_number`, só dígitos)." sync_mode: type: string enum: - scheduled - manual - on_access description: "Quando a sincronização roda; ausente: `scheduled` na criação, mantido na atualização." freshness_seconds: type: integer minimum: 60 maximum: 604800 description: "`on_access`: por quantos segundos os registros sincronizados de um titular valem como atuais." fields: type: array items: $ref: "#/components/schemas/EntityFieldInputV1" minItems: 1 maxItems: 200 description: Os campos que a entidade mantém, em ordem. Na atualização, a lista inteira (casada por `key`). records_path: type: - string - "null" maxLength: 500 description: Caminho da lista de registros dentro da resposta, quando não detectado. sample: type: array items: type: object additionalProperties: {} maxItems: 50 description: Os registros da prévia, guardados para reinferir campos depois. required: - integration_id - key - name - name_plural - fields EntityUpdateRequest: type: object properties: key: type: string maxLength: 63 description: Nome de máquina que os blocos do portal usam; único no workspace (até 63 caracteres). name: type: string maxLength: 200 name_plural: type: string maxLength: 200 description: type: - string - "null" maxLength: 2000 identifier_field_key: type: - string - "null" maxLength: 63 label_field_key: type: - string - "null" maxLength: 63 owner_field_key: type: - string - "null" maxLength: 63 description: Campo com o ID do titular, casado com o `tenant_id` do usuário do portal. Sem ele a entidade não aparece no portal. owner_match: type: string enum: - external_id - document_number description: "Como o campo do titular é comparado com o `tenant_id`: como texto (`external_id`) ou como CPF/CNPJ (`document_number`, só dígitos)." sync_mode: type: string enum: - scheduled - manual - on_access description: "Quando a sincronização roda; ausente: `scheduled` na criação, mantido na atualização." freshness_seconds: type: integer minimum: 60 maximum: 604800 description: "`on_access`: por quantos segundos os registros sincronizados de um titular valem como atuais." fields: type: array items: $ref: "#/components/schemas/EntityFieldInputV1" minItems: 1 maxItems: 200 description: Os campos que a entidade mantém, em ordem. Na atualização, a lista inteira (casada por `key`). pagination: allOf: - $ref: "#/components/schemas/EntityPaginationV1" - type: - object - "null" description: Paginação da sincronização; `null` = a detectada na operação (`operation_pagination`). sync_filters: type: array items: $ref: "#/components/schemas/EntitySyncFilterV1" maxItems: 20 description: Filtros da sincronização (até 20); ausente mantém os atuais. required: - key - name - name_plural - fields EntityJoinRequest: type: object properties: key: type: string maxLength: 63 description: Nome de máquina que os blocos do portal usam; único no workspace (até 63 caracteres). name: type: string maxLength: 200 name_plural: type: string maxLength: 200 description: type: - string - "null" maxLength: 2000 join: $ref: "#/components/schemas/EntityJoinSpecV1" fields: type: array items: type: object properties: from: type: string enum: - base - related field_key: type: string maxLength: 63 key: type: string maxLength: 63 name: type: string maxLength: 200 required: - from - field_key minItems: 1 maxItems: 200 description: "Os campos trazidos de cada lado: `{ from: base|related, field_key, key?, name? }`." label_field_key: type: - string - "null" maxLength: 63 description: Campo de título; ausente = a cópia do título da entidade base, `null` = nenhum. owner_field_key: type: - string - "null" maxLength: 63 description: Campo do titular; ausente = a cópia do titular da entidade base, `null` = nenhum. required: - key - name - name_plural - join - fields EntityTenantSyncRequest: type: object properties: tenant_id: type: string minLength: 1 maxLength: 500 description: Tenant ID (ID do titular) a sincronizar. Vai no corpo porque pode conter qualquer caractere. full: type: boolean description: Quando `true`, relê todos os registros do titular. required: - tenant_id PortalBuilderPageSeoV1: type: object properties: description: type: string keywords: type: string robots: type: string canonical: type: string og_title: type: string og_description: type: string og_image: type: string description: Nome do arquivo da og:image enviada. og_image_url: type: string description: URL pública da og:image — a que as prévias de link buscam (`POST /portal_builder/og_image`). og_image_meta: type: string description: Meta tags e Open Graph da página; campos vazios usam o SEO padrão. PortalBuilderThemeV1: type: object properties: light: type: object additionalProperties: type: string description: Cores da paleta, por token (`background`, `primary`…). dark: type: object additionalProperties: type: string description: Cores da paleta, por token (`background`, `primary`…). radius: type: string description: Raio das bordas, em `rem` ou `px`. example: 0.5rem required: - light - dark - radius description: "Tema visual do portal: paletas clara e escura e raio das bordas." PortalBuilderSeoDefaultsV1: type: object properties: description: type: string keywords: type: string robots: type: string og_title: type: string og_description: type: string og_image: type: string description: Nome do arquivo da og:image enviada. og_image_url: type: string description: URL pública da og:image — a que as prévias de link buscam (`POST /portal_builder/og_image`). og_image_meta: type: string required: - description - keywords - robots - og_title - og_description - og_image - og_image_url - og_image_meta description: Meta tags e Open Graph que toda página usa quando não define os seus. PortalBuilderPageV1: type: object properties: id: type: string description: Id estável da página. name: type: string description: Nome da página no construtor e no menu do portal. path: type: string description: Caminho da página na URL do portal. example: / title: type: string description: Título da aba do navegador. seo: $ref: "#/components/schemas/PortalBuilderPageSeoV1" show_in_menu: type: boolean description: Aparece no menu do cabeçalho do portal. Padrão `true`. content: type: object additionalProperties: {} description: "Árvore de blocos da página (dados do Puck). Opaca para a API: é guardada e devolvida como enviada." badge: type: string enum: - "" - nova - alterada description: "Em relação à versão no ar: `nova`, `alterada` ou vazio (igual)." required: - id - name - path - title - seo - content - badge PortalVersionPageV1: type: object properties: id: type: string description: Id estável da página. name: type: string description: Nome da página no construtor e no menu do portal. path: type: string description: Caminho da página na URL do portal. example: / title: type: string description: Título da aba do navegador. seo: $ref: "#/components/schemas/PortalBuilderPageSeoV1" show_in_menu: type: boolean description: Aparece no menu do cabeçalho do portal. Padrão `true`. content: type: object additionalProperties: {} description: "Árvore de blocos da página (dados do Puck). Opaca para a API: é guardada e devolvida como enviada." required: - id - name - path - title - seo - content PortalVersionV1: type: object properties: id: type: string format: uuid number: type: - integer - "null" description: Número sequencial da versão (v1, v2…). status: type: string enum: - draft - published - archived description: "`published` (no ar), `archived` (substituída) ou `draft`." note: type: - string - "null" description: Nota informada ao publicar. summary: type: - string - "null" description: "O que a versão mudou: a nota, ou o registro de alterações." published_by_email: type: - string - "null" published_by_name: type: - string - "null" published_at: type: - string - "null" format: date-time required: - id - number - status - note - summary - published_by_email - published_by_name - published_at PortalBuilderV1: type: object properties: portal: type: object properties: company_name: type: string title: type: string subtitle: type: string public_host: type: - string - "null" description: Endereço público do portal (domínio próprio ativo, ou o padrão). required: - company_name - title - subtitle - public_host description: Identidade do portal (Configurações do portal). draft: type: - object - "null" properties: revision: type: integer description: "Trava otimista do rascunho: envie-a no próximo salvamento ou publicação." dirty: type: boolean description: "`true` quando o rascunho difere da versão no ar." pages: type: array items: $ref: "#/components/schemas/PortalBuilderPageV1" editor_state: type: object additionalProperties: {} description: Estado que o construtor guarda ao lado das páginas (registro de alterações, conexões). Devolva o que leu. required: - revision - dirty - pages - editor_state description: O rascunho; `null` antes da primeira edição. live_version: type: integer description: Número da versão no ar; `0` quando nada foi publicado. versions: type: array items: $ref: "#/components/schemas/PortalVersionV1" theme: $ref: "#/components/schemas/PortalBuilderThemeV1" seo_defaults: $ref: "#/components/schemas/PortalBuilderSeoDefaultsV1" required: - portal - draft - live_version - versions - theme - seo_defaults PortalBuilderResponse: type: object properties: data: $ref: "#/components/schemas/PortalBuilderV1" required: - data PortalBuilderPageInput: type: object properties: id: type: string description: Id estável da página (letras, dígitos, `_` e `-`; até 100). Único no rascunho. name: type: string description: Nome da página no construtor e no menu do portal. path: type: string description: Caminho da página na URL do portal. title: type: string description: Título da aba do navegador. seo: $ref: "#/components/schemas/PortalBuilderPageSeoV1" show_in_menu: type: boolean description: Aparece no menu do cabeçalho do portal. Padrão `true`. content: type: object additionalProperties: {} description: "Árvore de blocos da página (dados do Puck). Opaca para a API: é guardada e devolvida como enviada." required: - id - name - path PortalBuilderDraftRequest: type: object properties: revision: type: integer minimum: 0 description: A `revision` do rascunho lida por último (`0` quando ainda não há rascunho). pages: type: array items: $ref: "#/components/schemas/PortalBuilderPageInput" maxItems: 200 description: Todas as páginas do rascunho, na ordem do menu (até 200). Páginas omitidas saem do rascunho. editor_state: type: object additionalProperties: {} description: Estado do editor; devolva o que leu. Omitido = `{}`. theme: allOf: - $ref: "#/components/schemas/PortalBuilderThemeV1" - description: Novo tema. Omitido = mantém o atual. seo_defaults: allOf: - $ref: "#/components/schemas/PortalBuilderSeoDefaultsV1" - description: Novo SEO padrão. Omitido = mantém o atual. required: - revision - pages PortalBuilderPublishRequest: type: object properties: revision: type: integer minimum: 0 description: A `revision` do rascunho lida por último (`0` quando ainda não há rascunho). pages: type: array items: $ref: "#/components/schemas/PortalBuilderPageInput" maxItems: 200 description: Todas as páginas do rascunho, na ordem do menu (até 200). Páginas omitidas saem do rascunho. editor_state: type: object additionalProperties: {} description: Estado do editor; devolva o que leu. Omitido = `{}`. theme: allOf: - $ref: "#/components/schemas/PortalBuilderThemeV1" - description: Novo tema. Omitido = mantém o atual. seo_defaults: allOf: - $ref: "#/components/schemas/PortalBuilderSeoDefaultsV1" - description: Novo SEO padrão. Omitido = mantém o atual. note: type: string maxLength: 2000 description: O que mudou, exibido no histórico de versões. required: - revision - pages PortalBuilderDraftSaveResponse: type: object properties: data: type: object properties: revision: type: integer description: "Trava otimista do rascunho: envie-a no próximo salvamento ou publicação." dirty: type: boolean description: "`true` quando o rascunho difere da versão no ar." badges: type: object additionalProperties: type: string enum: - "" - nova - alterada description: "Marca de cada página por id: `nova`, `alterada` ou vazio." required: - revision - dirty - badges required: - data PortalBuilderPublishResponse: type: object properties: data: type: object properties: revision: type: integer description: "Trava otimista do rascunho: envie-a no próximo salvamento ou publicação." version: $ref: "#/components/schemas/PortalVersionV1" required: - revision - version required: - data PortalVersionDetailResponse: type: object properties: data: type: object properties: version: $ref: "#/components/schemas/PortalVersionV1" pages: type: array items: $ref: "#/components/schemas/PortalVersionPageV1" required: - version - pages required: - data PortalBuilderRollbackResponse: type: object properties: data: type: object properties: version: $ref: "#/components/schemas/PortalVersionV1" builder: $ref: "#/components/schemas/PortalBuilderV1" required: - version - builder required: - data PortalBuilderSecretRequest: type: object properties: value: type: string minLength: 1 maxLength: 4000 description: O valor em texto puro a criptografar. Nunca é devolvido. url: type: string minLength: 1 maxLength: 2000 description: "A URL do webhook a que o valor se destina (obrigatória): o segredo só abre para uma requisição à mesma origem (esquema, domínio e porta). O domínio precisa ser fixo — sem `{{variáveis}}`." example: https://hooks.example.com/in required: - value - url PortalBuilderSecretResponse: type: object properties: data: type: object properties: value: type: string description: Valor criptografado (`secret:…`) para guardar no bloco. example: secret:… required: - value required: - data PortalBuilderOgImageRequest: type: object properties: filename: type: string minLength: 1 maxLength: 300 description: Nome original do arquivo. example: cover.png content_type: type: string enum: - image/png - image/jpeg - image/webp content_base64: type: string description: Os bytes da imagem em base64 (um prefixo `data:…;base64,` é aceito). required: - filename - content_type - content_base64 PortalBuilderOgImageResponse: type: object properties: data: type: object properties: url: type: string description: URL pública da imagem. content_type: type: string size: type: integer description: Tamanho da imagem, em bytes. required: - url - content_type - size required: - data PortalBuilderFormSubmissionRequest: type: object properties: form_id: type: string minLength: 1 maxLength: 200 description: Id do bloco Formulário. form_title: type: string maxLength: 200 page_path: type: string maxLength: 500 description: Caminho da página onde o bloco está. Padrão `/`. fields: type: array items: type: object properties: label: type: string maxLength: 200 name: type: string maxLength: 100 type: type: string enum: - text - email - textarea - regex - phone - url - number - currency_brl - currency - cpf - cnpj - cpf_cnpj required: type: boolean pattern: type: string maxLength: 500 description: Expressão regular de validação do campo. Uma com formato perigoso (ReDoS) responde 422. required: - label minItems: 1 maxItems: 30 action: type: object properties: type: type: string enum: - email - webhook email_to: type: string maxLength: 2000 description: Destinatários do e-mail, separados por vírgula (ação `email`). email_subject: type: string maxLength: 300 email_template: type: string maxLength: 20000 webhook_endpoint_id: type: string maxLength: 100 description: Id do webhook do workspace que recebe o envio (ação `webhook`). required: - type values: type: object additionalProperties: type: string description: Valores preenchidos, por nome do campo. submitter: type: object properties: name: type: string maxLength: 200 email: type: string maxLength: 254 description: Cliente que a prévia representa, para `{{customer_name}}` / `{{customer_email}}`. required: - form_id - fields - action PortalBuilderFormSubmissionResponse: type: object properties: data: type: object properties: submission_id: type: string action: type: string enum: - email - webhook event_id: type: string recipients: type: array items: type: string failed_recipients: type: array items: type: string notification_ids: type: array items: type: string webhook_delivery_id: type: - string - "null" webhook_url: type: - string - "null" required: - submission_id - action - event_id - recipients - failed_recipients - notification_ids - webhook_delivery_id - webhook_url required: - data PortalBuilderActionRunRequest: type: object properties: block_id: type: string minLength: 1 maxLength: 200 description: Id do bloco Botão de ação. label: type: string maxLength: 200 page_path: type: string maxLength: 500 description: Caminho da página onde o bloco está. Padrão `/`. request: type: object properties: method: type: string enum: - POST - PUT - PATCH url: type: string maxLength: 2000 description: URL completa do webhook; precisa começar com https://. headers: type: array items: type: object properties: key: type: string maxLength: 200 value: type: string maxLength: 8000 required: - key - value maxItems: 50 description: Cabeçalhos da requisição (até 50); um valor pode ser um `secret:` de `POST /portal_builder/secrets`. body: type: string maxLength: 100000 required: - method - url submitter: type: object properties: name: type: string maxLength: 200 email: type: string maxLength: 254 description: Cliente que a prévia representa, para `{{customer_name}}` / `{{customer_email}}`. required: - block_id - request PortalBuilderActionRunResponse: type: object properties: data: type: object properties: run_id: type: string event_id: type: string success: type: boolean http_status: type: - integer - "null" description: Status HTTP devolvido pelo destino; `null` quando não houve resposta. method: type: string url: type: string duration_ms: type: integer error: type: - string - "null" required: - run_id - event_id - success - http_status - method - url - duration_ms - error required: - data PortalColorsV1: type: object properties: primary: type: string primary_foreground: type: string secondary: type: string secondary_foreground: type: string accent: type: string accent_foreground: type: string background: type: string foreground: type: string card: type: string card_foreground: type: string border: type: string input: type: string ring: type: string destructive: type: string destructive_foreground: type: string muted: type: string muted_foreground: type: string popover: type: string popover_foreground: type: string description: "Cores do tema, em HSL sem o `hsl()` (ex.: `210 40% 98%`). Chaves omitidas usam o padrão." example: primary: 222 47% 11% PortalSettingsV1: type: object properties: id: type: - string - "null" format: uuid description: ID da configuração; `null` enquanto o portal nunca foi configurado (os valores são os padrões). workspace_id: type: string format: uuid company_name: type: string description: "Nome exibido no portal. Padrão: o nome da organização." title: type: - string - "null" subtitle: type: - string - "null" logo_url: type: - string - "null" description: URL pública do logo (fundos claros). logo_light_url: type: - string - "null" description: URL pública do logo para fundos escuros. favicon_url: type: - string - "null" html_lang: type: string enum: - pt-BR - en-US - es-ES description: "O idioma do portal: o atributo `lang` do `` das páginas e o idioma das telas de login." light_colors: $ref: "#/components/schemas/PortalColorsV1" dark_colors: $ref: "#/components/schemas/PortalColorsV1" signup_slug: type: - string - "null" description: "Endereço do portal na plataforma: `/portal/{signup_slug}/login`." enable_login: type: boolean description: Chave geral do login do portal. enable_email_login: type: boolean description: Permite entrar com e-mail e senha ou link mágico (exige `enable_login`). allow_password_change: type: boolean sso_enabled: type: boolean description: Login por SSO com um JWT assinado pelo seu sistema. sso_public_key: type: - string - "null" description: Chave PÚBLICA (PEM) que verifica o JWT de SSO. Nunca envie a chave privada. sso_algorithm: type: - string - "null" enum: - RS256 - RS384 - RS512 - ES256 - ES384 - ES512 - PS256 - PS384 - PS512 sso_issuer: type: - string - "null" portal_slug: type: - string - "null" description: Subdomínio do endereço `https://{portal_slug}.{portal_domain}`. Altere em `PATCH /portal_settings/domain`. portal_domain: type: - string - "null" available_domains: type: array items: type: string description: Domínios da plataforma aceitos em `portal_domain`. notification_type_statuses: type: object properties: account_suspended: type: string enum: - ACTIVE - INACTIVE - DISABLED account_activated: type: string enum: - ACTIVE - INACTIVE - DISABLED portal_invitation: type: string enum: - ACTIVE - INACTIVE - DISABLED welcome: type: string enum: - ACTIVE - INACTIVE - DISABLED description: "Situação de cada notificação do portal: `ACTIVE` (envia), `INACTIVE` (silenciada) ou `DISABLED` (indisponível)." notification_bcc_emails: type: array items: type: object properties: label: type: string description: Rótulo de identificação (apenas exibição). address: type: string format: email required: - label - address description: Destinatários em cópia oculta de todo e-mail de notificação. notification_sender_name: type: - string - "null" notification_sender_email: type: - string - "null" description: Remetente dos e-mails de notificação. Só passa a ser usado quando `notification_sender_email_status` é `active`. notification_reply_to_email: type: - string - "null" notification_sender_email_status: type: - string - "null" enum: - pending - active - failed description: "Verificação do remetente no AWS SES: `pending`, `active` ou `failed`; `null` quando não há remetente próprio." hsts_include_subdomains: type: boolean hsts_preload: type: boolean secure_frame_headers: type: boolean description: Impede que o portal seja exibido dentro de iframes de outros sites. seo_indexing_enabled: type: boolean seo_robots_txt: type: - string - "null" seo_sitemap_enabled: type: boolean seo_google_site_verification: type: - string - "null" seo_canonical_url: type: - string - "null" tracking_integrations: type: object additionalProperties: type: object additionalProperties: anyOf: - type: string - type: boolean description: "Rastreadores por provedor (`google_tag_manager`, `google_analytics`, …): `{ provedor: { enabled, ...ids } }`. Provedores e campos desconhecidos são descartados." chat_integrations: type: object additionalProperties: type: object additionalProperties: anyOf: - type: string - type: boolean description: Widgets de chat por provedor (`intercom`, `hubspot`, `zendesk`, …), no mesmo formato de `tracking_integrations`. custom_code: type: - string - "null" description: JavaScript próprio executado em todas as páginas do portal. required: - id - workspace_id - company_name - title - subtitle - logo_url - logo_light_url - favicon_url - html_lang - light_colors - dark_colors - signup_slug - enable_login - enable_email_login - allow_password_change - sso_enabled - sso_public_key - sso_algorithm - sso_issuer - portal_slug - portal_domain - available_domains - notification_type_statuses - notification_bcc_emails - notification_sender_name - notification_sender_email - notification_reply_to_email - notification_sender_email_status - hsts_include_subdomains - hsts_preload - secure_frame_headers - seo_indexing_enabled - seo_robots_txt - seo_sitemap_enabled - seo_google_site_verification - seo_canonical_url - tracking_integrations - chat_integrations - custom_code PortalSettingsResponse: type: object properties: data: $ref: "#/components/schemas/PortalSettingsV1" required: - data PortalSettingsUpdateRequest: type: object properties: company_name: type: string minLength: 1 maxLength: 100 title: type: - string - "null" maxLength: 100 subtitle: type: - string - "null" maxLength: 200 html_lang: type: string enum: - pt-BR - en-US - es-ES description: "O idioma do portal: vai no `lang` do `` das páginas e traduz as telas de login." light_colors: $ref: "#/components/schemas/PortalColorsV1" dark_colors: $ref: "#/components/schemas/PortalColorsV1" signup_slug: type: - string - "null" maxLength: 50 description: Letras minúsculas, números e hífens; único na plataforma. `null` ou `""` remove. enable_login: type: boolean enable_email_login: type: boolean allow_password_change: type: boolean sso_enabled: type: boolean sso_public_key: type: - string - "null" maxLength: 10000 sso_algorithm: type: - string - "null" enum: - RS256 - RS384 - RS512 - ES256 - ES384 - ES512 - PS256 - PS384 - PS512 sso_issuer: type: - string - "null" maxLength: 500 notification_type_statuses: type: object properties: account_suspended: type: string enum: - ACTIVE - INACTIVE - DISABLED account_activated: type: string enum: - ACTIVE - INACTIVE - DISABLED portal_invitation: type: string enum: - ACTIVE - INACTIVE - DISABLED welcome: type: string enum: - ACTIVE - INACTIVE - DISABLED description: "Situação de cada notificação do portal: `ACTIVE` (envia), `INACTIVE` (silenciada) ou `DISABLED` (indisponível)." notification_bcc_emails: type: array items: type: object properties: label: type: string description: Rótulo de identificação (apenas exibição). address: type: string format: email required: - address maxItems: 20 description: Substitui a lista inteira (até 20). notification_sender_name: type: - string - "null" maxLength: 100 notification_sender_email: type: - string - "null" maxLength: 254 description: Um endereço novo inicia a verificação no AWS SES, que envia um link de confirmação para ele. `""` volta ao remetente da plataforma. notification_reply_to_email: type: - string - "null" maxLength: 254 hsts_include_subdomains: type: boolean hsts_preload: type: boolean secure_frame_headers: type: boolean seo_indexing_enabled: type: boolean seo_robots_txt: type: - string - "null" seo_sitemap_enabled: type: boolean seo_google_site_verification: type: - string - "null" description: Apenas o conteúdo da meta tag de verificação do Google. seo_canonical_url: type: - string - "null" maxLength: 500 tracking_integrations: type: object additionalProperties: type: object additionalProperties: anyOf: - type: string - type: boolean description: "Rastreadores por provedor (`google_tag_manager`, `google_analytics`, …): `{ provedor: { enabled, ...ids } }`. Provedores e campos desconhecidos são descartados." chat_integrations: type: object additionalProperties: type: object additionalProperties: anyOf: - type: string - type: boolean description: Widgets de chat por provedor (`intercom`, `hubspot`, `zendesk`, …), no mesmo formato de `tracking_integrations`. custom_code: type: - string - "null" maxLength: 100000 description: 'Atualização parcial: só os campos enviados mudam. `""` limpa os textos opcionais.' PortalLogoUploadRequest: type: object properties: filename: type: string minLength: 1 maxLength: 255 example: logo.png content_type: type: string description: "`image/png`, `image/jpeg` ou `image/webp`; o favicon aceita também `image/x-icon`. SVG não é aceito." example: image/png content_base64: type: string description: Conteúdo do arquivo em base64 (até 500 KB depois de decodificado). variant: type: string enum: - logo - logo_light - favicon description: "Qual imagem: `logo` (padrão), `logo_light` (logo para fundos escuros) ou `favicon`." required: - filename - content_type - content_base64 PortalLogoUploadResponse: type: object properties: data: type: object properties: variant: type: string enum: - logo - logo_light - favicon url: type: string required: - variant - url required: - data PortalLogoDeleteResponse: type: object properties: data: type: object properties: variant: type: string enum: - logo - logo_light - favicon deleted: type: boolean required: - variant - deleted required: - data PortalDomainUpdateRequest: type: object properties: slug: type: - string - "null" minLength: 3 maxLength: 50 description: "Subdomínio: 3 a 50 letras minúsculas, números e hífens (sem hífen nas pontas). `null` para remover." example: acme domain: type: - string - "null" description: Um dos domínios da plataforma (`available_domains`). `null` para remover. required: - slug - domain PortalDomainResponse: type: object properties: data: type: object properties: portal_slug: type: - string - "null" portal_domain: type: - string - "null" full_url: type: - string - "null" description: Endereço completo do portal, ou `null` quando não há um. required: - portal_slug - portal_domain - full_url required: - data PortalSlugCheckResponse: type: object properties: data: type: object properties: slug: type: string domain: type: string available: type: boolean reason: type: - string - "null" enum: - invalid_format - reserved - invalid_domain - taken description: "Por que não está disponível: `invalid_format`, `reserved`, `invalid_domain` ou `taken`; `null` quando está." required: - slug - domain - available - reason required: - data PortalSenderIdentityResponse: type: object properties: data: type: object properties: status: type: - string - "null" enum: - pending - active - failed description: "Verificação do remetente no AWS SES: `pending`, `active` ou `failed`; `null` quando não há remetente próprio." verification_requested: type: boolean description: "`true` quando uma nova verificação foi pedida (um e-mail foi enviado ao remetente)." required: - status - verification_requested required: - data PortalCustomDomainV1: type: object properties: id: type: string format: uuid hostname: type: string example: portal.example.com status: type: string enum: - pending_verification - dns_verified - pending_certificate - generating_certificate - active - certificate_failed - failed description: "Etapa do provisionamento: `pending_verification`, `dns_verified`, `pending_certificate`, `generating_certificate`, `active`, `certificate_failed` ou `failed`." verified_at: type: - string - "null" format: date-time last_verification_at: type: - string - "null" format: date-time verification_error: type: - string - "null" certificate_managed: type: boolean description: "`true` quando o certificado é emitido e renovado pela CloudFront (basta o CNAME de roteamento)." certificate_issued_at: type: - string - "null" format: date-time certificate_expires_at: type: - string - "null" format: date-time certificate_last_renewal_at: type: - string - "null" format: date-time certificate_last_renewal_error: type: - string - "null" ownership_verified_at: type: - string - "null" format: date-time description: Quando o TXT de propriedade foi encontrado; `null` enquanto não foi — ou depois que a propriedade foi perdida (`ownership_lost`). ownership_lost: type: boolean description: "`true` quando o domínio já foi comprovado, mas a verificação diária deixou de encontrar o TXT `_dashmagico-verify.{hostname}` (3 verificações seguidas ao longo de 7 dias ou mais): o portal deixa de responder nele até o TXT ser publicado de novo e o domínio validado." ownership_missing_since: type: - string - "null" format: date-time description: Desde quando a verificação diária não encontra o TXT de propriedade de um domínio comprovado (ainda não perdido); `null` quando a última verificação o encontrou. dns_records: type: array items: type: object properties: type: type: string enum: - TXT - CNAME name: type: string value: type: string purpose: type: string enum: - ownership_verification - routing - certificate_validation required: - type - name - value - purpose description: "Registros DNS que precisam ser publicados no domínio. O TXT `_dashmagico-verify.{hostname}` (`ownership_verification`) prova que o domínio é seu: o valor é exclusivo deste registro, e nada é provisionado nem roteado antes dele. Mantenha o TXT publicado: a propriedade é verificada de novo todos os dias, e o domínio a perde se o registro sumir em 3 verificações seguidas ao longo de 7 dias ou mais." created_at: type: string format: date-time required: - id - hostname - status - verified_at - last_verification_at - verification_error - certificate_managed - certificate_issued_at - certificate_expires_at - certificate_last_renewal_at - certificate_last_renewal_error - ownership_verified_at - ownership_lost - ownership_missing_since - dns_records - created_at PortalCustomDomainListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/PortalCustomDomainV1" required: - data PortalCustomDomainResponse: type: object properties: data: $ref: "#/components/schemas/PortalCustomDomainV1" required: - data PortalCustomDomainCreateRequest: type: object properties: hostname: type: string minLength: 4 maxLength: 253 description: "Nome completo do domínio, ex.: `portal.exemplo.com.br`." example: portal.example.com required: - hostname PortalCustomDomainDnsStatusResponse: type: object properties: data: type: object properties: status: type: string enum: - pending_verification - dns_verified - pending_certificate - generating_certificate - active - certificate_failed - failed ownership_ok: type: boolean description: O TXT `_dashmagico-verify.{hostname}` tem o valor deste domínio (ou a propriedade já foi comprovada). routing_ok: type: boolean description: O CNAME de roteamento aponta para a plataforma. validation_ok: type: boolean description: O CNAME de validação do certificado está correto (sempre `true` com certificado gerenciado). ownership_error: type: - string - "null" routing_error: type: - string - "null" validation_error: type: - string - "null" required: - status - ownership_ok - routing_ok - validation_ok - ownership_error - routing_error - validation_error required: - data PortalSettingsDeletedResponse: type: object properties: data: type: object properties: id: type: string format: uuid deleted: type: boolean example: true required: - id - deleted required: - data PortalOAuthProviderV1: type: object properties: id: type: string format: uuid enabled: type: boolean name: type: string button_label: type: - string - "null" description: Texto do botão de login; quando vazio, usa o nome. issuer_url: type: string description: URL do emissor OpenID Connect (https em produção). client_id: type: string scopes: type: string description: "Escopos separados por espaço. Padrão: `openid email profile`." email_claim: type: string description: "Claim do token que traz o e-mail. Padrão: `email`." has_secret: type: boolean description: Se há um client secret armazenado. O secret nunca é retornado. created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - enabled - name - button_label - issuer_url - client_id - scopes - email_claim - has_secret - created_at - updated_at PortalOAuthProviderListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/PortalOAuthProviderV1" required: - data PortalOAuthProviderResponse: type: object properties: data: $ref: "#/components/schemas/PortalOAuthProviderV1" required: - data PortalOAuthProviderCreateRequest: type: object properties: name: type: string minLength: 1 maxLength: 100 button_label: type: - string - "null" maxLength: 100 description: Texto do botão de login; quando vazio, usa o nome. issuer_url: type: string maxLength: 2000 format: uri description: URL do emissor OpenID Connect (https em produção). client_id: type: string minLength: 1 maxLength: 500 client_secret: type: string minLength: 1 maxLength: 2000 description: "Somente escrita: guardado criptografado e nunca retornado." scopes: type: string maxLength: 500 description: "Escopos separados por espaço. Padrão: `openid email profile`." email_claim: type: string maxLength: 100 description: "Claim do token que traz o e-mail. Padrão: `email`." enabled: type: boolean required: - name - issuer_url - client_id - client_secret PortalOAuthProviderUpdateRequest: type: object properties: name: type: string minLength: 1 maxLength: 100 button_label: type: - string - "null" maxLength: 100 issuer_url: type: string maxLength: 2000 format: uri client_id: type: string minLength: 1 maxLength: 500 client_secret: type: string maxLength: 2000 description: Omitido ou vazio mantém o secret atual; um valor substitui. Nunca retornado. scopes: type: string maxLength: 500 email_claim: type: string maxLength: 100 enabled: type: boolean PortalOAuthProviderTestRequest: type: object properties: issuer_url: type: string maxLength: 2000 format: uri description: URL do emissor OpenID Connect (https em produção). required: - issuer_url PortalOAuthProviderTestResponse: type: object properties: data: type: object properties: ok: type: boolean issuer: type: - string - "null" authorization_endpoint: type: - string - "null" token_endpoint: type: - string - "null" jwks_uri: type: - string - "null" error: type: - string - "null" description: Motivo da falha quando `ok` é `false`. required: - ok - issuer - authorization_endpoint - token_endpoint - jwks_uri - error required: - data WebhookV1: type: object properties: id: type: string format: uuid public_id: type: - string - "null" format: uuid description: Identificador público do endpoint. url: type: string description: URL que recebe os eventos via POST. description: type: - string - "null" description: Descrição livre do endpoint. auth_type: type: string enum: - none - basic - bearer - header description: "Autenticação enviada em cada entrega: `none`, `basic`, `bearer` ou `header`." active: type: boolean description: Quando `false`, o endpoint está pausado e não recebe entregas. workspace_id: type: string format: uuid description: Workspace do endpoint. Ele recebe os eventos deste workspace e os eventos da organização. created_at: type: string format: date-time updated_at: type: string format: date-time events: type: array items: type: string description: "Tipos de evento assinados (ex.: `api_key.db.created`)." metadata: type: - object - "null" additionalProperties: {} description: Metadados internos somente leitura. custom_metadata: type: - object - "null" additionalProperties: {} description: Metadados livres definidos pela organização. delivery_count: type: integer description: Total de entregas registradas para o endpoint (listagem e detalhe). required: - id - public_id - url - description - auth_type - active - workspace_id - created_at - updated_at - events - metadata - custom_metadata description: Endpoint de webhook do workspace. O segredo de assinatura e as credenciais de autenticação nunca são retornados aqui. WebhookWithSecretV1: allOf: - $ref: "#/components/schemas/WebhookV1" - type: object properties: secret: type: string description: Segredo de assinatura (HMAC-SHA256) em texto claro. Retornado SOMENTE na criação e na rotação — guarde-o nesse momento. example: whsec_… required: - secret description: Endpoint de webhook do workspace. O segredo de assinatura e as credenciais de autenticação nunca são retornados aqui. WebhookListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/WebhookV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta WebhookResponse: type: object properties: data: $ref: "#/components/schemas/WebhookV1" required: - data WebhookWithSecretResponse: type: object properties: data: $ref: "#/components/schemas/WebhookWithSecretV1" required: - data WebhookCreateRequest: type: object properties: url: type: string description: URL do endpoint (obrigatória na criação). Precisa ser uma URL válida. example: https://example.com/webhooks events: type: array items: type: string minItems: 1 description: Tipos de evento a receber. Pelo menos um. example: - api_key.db.created description: type: - string - "null" description: Descrição livre. `null` limpa. auth_type: type: string enum: - none - basic - bearer - header description: Autenticação das entregas (padrão `none`). Ao alterar, envie também o `auth_config` correspondente. auth_config: type: - object - "null" additionalProperties: {} description: "Credenciais do `auth_type`: basic → `{ username, password }`, bearer → `{ token }`, header → `{ key, value }`. Guardadas criptografadas e nunca retornadas." example: token: token-123 required: - url - events WebhookUpdateRequest: type: object properties: url: type: string description: URL do endpoint (obrigatória na criação). Precisa ser uma URL válida. events: type: array items: type: string minItems: 1 description: Tipos de evento a receber. Pelo menos um. description: type: - string - "null" description: Descrição livre. `null` limpa. active: type: boolean description: "`false` pausa o endpoint; `true` retoma." auth_type: type: string enum: - none - basic - bearer - header description: Autenticação das entregas (padrão `none`). Ao alterar, envie também o `auth_config` correspondente. auth_config: type: - object - "null" additionalProperties: {} description: "Credenciais do `auth_type`: basic → `{ username, password }`, bearer → `{ token }`, header → `{ key, value }`. Guardadas criptografadas e nunca retornadas." example: token: token-123 WebhookTestResponse: type: object properties: data: type: object properties: success: type: boolean description: "`true` quando o endpoint respondeu 2xx." status_code: type: - integer - "null" description: Status HTTP da resposta; `null` quando não houve resposta. delivery_id: type: string format: uuid description: Entrega registrada para a tentativa. error: type: - string - "null" description: Motivo da falha, quando houve. required: - success - status_code - delivery_id - error required: - data WebhookDeliveryRetryResponse: type: object properties: data: type: object properties: delivery_id: type: string format: uuid status: type: string enum: - queued description: Sempre `queued`. required: - delivery_id - status required: - data WebhookDeliveryV1: type: object properties: id: type: string format: uuid public_id: type: - string - "null" format: uuid webhook_endpoint_id: type: string format: uuid event_id: type: string format: uuid status: type: string enum: - pending - delivered - failed description: "`pending` (aguardando envio ou nova tentativa), `delivered` (2xx) ou `failed`." http_status: type: - integer - "null" description: Status HTTP retornado pelo endpoint. error: type: - string - "null" description: Motivo da falha, quando houve. attempts: type: integer description: Número de tentativas feitas. next_retry_at: type: - string - "null" format: date-time description: Quando a próxima tentativa automática está agendada. delivered_at: type: - string - "null" format: date-time created_at: type: string format: date-time request_headers: type: - object - "null" additionalProperties: {} description: Cabeçalhos enviados (autenticação e assinatura como `[REDACTED]`). request_body: description: Payload JSON enviado. response_headers: type: - object - "null" additionalProperties: {} response_body: type: - string - "null" description: Corpo da resposta do endpoint (até 10.000 caracteres). event_type: type: - string - "null" description: Tipo do evento entregue (listagem global e detalhe). webhook_endpoint: type: object properties: id: type: string format: uuid url: type: string description: type: - string - "null" required: - id - url - description description: Resumo do endpoint de destino (listagem global e detalhe). required: - id - public_id - webhook_endpoint_id - event_id - status - http_status - error - attempts - next_retry_at - delivered_at - created_at - request_headers - response_headers - response_body description: Uma tentativa de entrega de evento a um endpoint de webhook. Cabeçalhos de autenticação e assinatura são gravados como `[REDACTED]`. WebhookDeliveryListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/WebhookDeliveryV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta WebhookDeliveryResponse: type: object properties: data: $ref: "#/components/schemas/WebhookDeliveryV1" required: - data EventV1: type: object properties: id: type: string format: uuid type: type: string description: Tipo do evento. example: api_key.rotated resource_type: type: string description: Tipo do recurso a que o evento se refere. resource_id: type: string format: uuid description: ID do recurso a que o evento se refere. workspace_id: type: - string - "null" format: uuid description: Workspace do evento; `null` para eventos da organização (visíveis em todo workspace). created_at: type: string format: date-time data: description: Payload do evento, como enviado aos webhooks. metadata: type: - object - "null" additionalProperties: {} description: Metadados do evento. required: - id - type - resource_type - resource_id - workspace_id - created_at - metadata description: Um evento do log — de onde os webhooks são disparados. Somente leitura. EventListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/EventV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta EventResponse: type: object properties: data: $ref: "#/components/schemas/EventV1" required: - data AuditLogV1: type: object properties: id: type: string format: uuid workspace_id: type: - string - "null" format: uuid description: Workspace do registro; `null` para ações da organização. user_id: type: - string - "null" description: Identificador de quem executou a ação, quando conhecido. user_email: type: - string - "null" description: E-mail de quem executou a ação; `null` para tokens de máquina. action: type: string description: Ação registrada. example: webhook.created resource_type: type: string description: Tipo do recurso afetado. resource_id: type: - string - "null" resource_name: type: - string - "null" ip_address: type: - string - "null" user_agent: type: - string - "null" created_at: type: string format: date-time changes: description: Alterações registradas (JSON livre). previous_values: description: Valores anteriores à ação (JSON livre). new_values: description: Valores após a ação (JSON livre). metadata: type: - object - "null" additionalProperties: {} description: "Contexto extra (ex.: `via_api`, `token_id`)." required: - id - workspace_id - user_id - user_email - action - resource_type - resource_id - resource_name - ip_address - user_agent - created_at - metadata description: "Um registro da trilha de auditoria: quem alterou o quê, quando e de onde. Somente leitura." AuditLogListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/AuditLogV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta AuditLogResponse: type: object properties: data: $ref: "#/components/schemas/AuditLogV1" required: - data AuditLogSummaryResponse: type: object properties: data: type: object properties: hours: type: number description: Janela usada, em horas. since: type: string format: date-time description: Início da janela. total_count: type: integer description: Total de registros na janela. action_counts: type: array items: type: object properties: action: type: string count: type: integer required: - action - count description: As 10 ações mais frequentes, com a contagem de cada uma. recent_logs: type: array items: $ref: "#/components/schemas/AuditLogV1" description: Os 20 registros mais recentes da janela. required: - hours - since - total_count - action_counts - recent_logs required: - data EmailTemplateV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Identificador público do modelo. organization_id: type: - string - "null" format: uuid description: Organização dona do modelo. `null` para um modelo padrão da plataforma, que só pode ser lido. name: type: string description: Nome do modelo, exibido para quem edita. type: type: string enum: - api_key_expiring - account_suspended - account_activated - portal_invitation - portal_signup_verification - magic_link_portal - magic_link_dashboard - email_verification - password_reset - welcome - email_change_verification - password_verification - account_invitation - organization_welcome - dashboard_user_welcome description: Tipo de notificação que o modelo renderiza. Cada tipo tem no máximo um modelo ativo por organização. Uma organização só cria modelos de `api_key_expiring`, `account_suspended` e `account_activated`; e-mails com link de acesso ou código (convite do portal, link de acesso, verificação, redefinição de senha) usam sempre o conteúdo da plataforma (422 `TEMPLATE_TYPE_NOT_EDITABLE`). subject: type: string description: Assunto do e-mail. Aceita variáveis `{{nome}}`. html_body: type: string description: Corpo HTML do e-mail. Aceita variáveis `{{nome}}`, cujos valores são escapados ao renderizar. text_body: type: - string - "null" description: Corpo alternativo em texto puro, quando houver. bcc: type: array items: type: string description: Endereços que recebem cópia oculta (CCO) de todo e-mail enviado com este modelo. variables: type: array items: type: string description: Nomes das variáveis que o modelo usa (documentação para quem edita). is_active: type: boolean description: Se é o modelo ativo do seu tipo. Os demais são rascunhos. custom_metadata: type: - object - "null" additionalProperties: {} description: Metadados arbitrários definidos pela organização (chave/valor). created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - public_id - organization_id - name - type - subject - html_body - text_body - bcc - variables - is_active - custom_metadata - created_at - updated_at EmailTemplateListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/EmailTemplateV1" required: - data EmailTemplateResponse: type: object properties: data: $ref: "#/components/schemas/EmailTemplateV1" required: - data EmailTemplateCreateRequest: type: object properties: name: type: string description: Nome do modelo (obrigatório na criação). type: type: string enum: - api_key_expiring - account_suspended - account_activated - portal_invitation - portal_signup_verification - magic_link_portal - magic_link_dashboard - email_verification - password_reset - welcome - email_change_verification - password_verification - account_invitation - organization_welcome - dashboard_user_welcome description: Tipo de notificação que o modelo renderiza (obrigatório). subject: type: string description: Assunto do e-mail, com variáveis `{{nome}}` (obrigatório na criação). html_body: type: string description: Corpo HTML, com variáveis `{{nome}}` (obrigatório na criação). text_body: type: - string - "null" description: Corpo alternativo em texto puro. `null` limpa. bcc: anyOf: - type: array items: type: string - type: string - type: "null" description: Lista (ou um único endereço) de e-mails em cópia oculta. Endereços inválidos geram 422; omitido na atualização, mantém a lista atual. variables: type: array items: type: string description: Nomes das variáveis que o modelo usa. is_active: type: boolean description: Torna este o modelo ativo do tipo; o ativo anterior vira rascunho. Padrão `false` na criação. required: - name - type - subject - html_body EmailTemplateUpdateRequest: type: object properties: name: type: string description: Nome do modelo (obrigatório na criação). subject: type: string description: Assunto do e-mail, com variáveis `{{nome}}` (obrigatório na criação). html_body: type: string description: Corpo HTML, com variáveis `{{nome}}` (obrigatório na criação). text_body: type: - string - "null" description: Corpo alternativo em texto puro. `null` limpa. bcc: anyOf: - type: array items: type: string - type: string - type: "null" description: Lista (ou um único endereço) de e-mails em cópia oculta. Endereços inválidos geram 422; omitido na atualização, mantém a lista atual. variables: type: array items: type: string description: Nomes das variáveis que o modelo usa. is_active: type: boolean description: Torna este o modelo ativo do tipo; o ativo anterior vira rascunho. Padrão `false` na criação. public_id: type: string format: uuid description: Novo identificador público (UUID), quando a organização permite escolhê-lo. EmailTemplateDuplicateRequest: type: object properties: new_name: type: string description: 'Nome da cópia. Padrão: " (Cópia)".' EmailTemplateRenderRequest: type: object properties: variables: type: object additionalProperties: {} description: Valores das variáveis `{{nome}}` do modelo. EmailTemplateRenderResponse: type: object properties: data: type: object properties: subject: type: string description: Assunto renderizado. html_body: type: string description: Corpo HTML renderizado. text_body: type: - string - "null" description: Corpo em texto puro renderizado, quando o modelo tem um. bcc: type: array items: type: string description: Cópias ocultas do modelo (somente na pré-visualização com dados de exemplo). required: - subject - html_body - text_body required: - data EmailTemplateDefaultsResponse: type: object properties: data: type: array items: type: object properties: type: type: string enum: - api_key_expiring - account_suspended - account_activated - portal_invitation - portal_signup_verification - magic_link_portal - magic_link_dashboard - email_verification - password_reset - welcome - email_change_verification - password_verification - account_invitation - organization_welcome - dashboard_user_welcome description: Tipo de notificação. created: type: boolean description: O modelo foi criado agora. updated: type: boolean description: O modelo existente foi sobrescrito com o padrão. id: type: - string - "null" format: uuid description: ID do modelo criado ou atualizado. error: type: - string - "null" description: Motivo da falha para este tipo, quando houve. required: - type - created - updated - id - error required: - data EmailLayoutV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Identificador público do layout. organization_id: type: string format: uuid description: Organização dona do layout. name: type: string description: Nome do layout. html_body: type: string description: Documento HTML que envolve o corpo dos e-mails, no lugar do marcador `{{content}}`. E-mails com link de acesso ou código usam sempre o layout da plataforma. is_default: type: boolean description: Se é o layout padrão da organização (no máximo um). is_active: type: boolean description: Se o layout está ativo. custom_metadata: type: - object - "null" additionalProperties: {} description: Metadados arbitrários definidos pela organização (chave/valor). created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - public_id - organization_id - name - html_body - is_default - is_active - custom_metadata - created_at - updated_at EmailLayoutListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/EmailLayoutV1" required: - data EmailLayoutResponse: type: object properties: data: $ref: "#/components/schemas/EmailLayoutV1" required: - data EmailLayoutCreateRequest: type: object properties: name: type: string description: Nome do layout (obrigatório na criação). html_body: type: string description: Documento HTML com o marcador `{{content}}` (obrigatório na criação; sem o marcador, 422). is_default: type: boolean description: Torna este o layout padrão; o padrão anterior deixa de ser. required: - name - html_body EmailLayoutUpdateRequest: type: object properties: name: type: string description: Nome do layout (obrigatório na criação). html_body: type: string description: Documento HTML com o marcador `{{content}}` (obrigatório na criação; sem o marcador, 422). is_default: type: boolean description: Torna este o layout padrão; o padrão anterior deixa de ser. is_active: type: boolean description: Ativa ou desativa o layout. NotificationV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Identificador público da notificação. workspace_id: type: - string - "null" format: uuid description: Workspace da notificação. `null` para uma notificação da organização inteira. type: type: string enum: - api_key_expiring - account_suspended - account_activated - portal_invitation - portal_signup_verification - magic_link_portal - magic_link_dashboard - email_verification - password_reset - welcome - email_change_verification - password_verification - account_invitation - organization_welcome - dashboard_user_welcome description: Tipo de notificação. channel: type: string enum: - email - in_app - webhook description: Canal de envio. status: type: string enum: - pending - sent - delivered - failed - read - skipped description: "`pending` (na fila), `sent`, `delivered`, `read`, `failed` ou `skipped` (não enviada porque o tipo estava inativo)." template_id: type: - string - "null" format: uuid description: Modelo de e-mail usado, quando houve. recipient: type: string description: Endereço de destino. recipient_type: type: - string - "null" description: "Tipo do destinatário: `portal_user`, `dashboard_user`, `organization` ou `external`." recipient_id: type: - string - "null" format: uuid description: ID do destinatário, quando é um registro. subject: type: - string - "null" description: Assunto renderizado. content: type: - string - "null" description: Corpo renderizado. variables: type: object additionalProperties: {} description: Variáveis usadas na renderização (sem as chaves internas `__*` do envio). sent_at: type: - string - "null" format: date-time description: Quando foi enviada. delivered_at: type: - string - "null" format: date-time description: Quando foi entregue. read_at: type: - string - "null" format: date-time description: Quando foi lida. failure_reason: type: - string - "null" description: Motivo da última falha de envio. retry_count: type: integer description: Tentativas de envio repetidas. scheduled_for: type: - string - "null" format: date-time description: Envio agendado para, quando houver. resource_type: type: - string - "null" description: Tipo do registro a que a notificação se refere. resource_id: type: - string - "null" format: uuid description: ID do registro a que a notificação se refere. template: type: - object - "null" properties: name: type: - string - "null" type: type: - string - "null" enum: - api_key_expiring - account_suspended - account_activated - portal_invitation - portal_signup_verification - magic_link_portal - magic_link_dashboard - email_verification - password_reset - welcome - email_change_verification - password_verification - account_invitation - organization_welcome - dashboard_user_welcome required: - name - type description: Nome e tipo do modelo usado (somente na listagem). created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - public_id - workspace_id - type - channel - status - template_id - recipient - recipient_type - recipient_id - subject - content - variables - sent_at - delivered_at - read_at - failure_reason - retry_count - scheduled_for - resource_type - resource_id - template - created_at - updated_at NotificationListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/NotificationV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta NotificationResponse: type: object properties: data: $ref: "#/components/schemas/NotificationV1" required: - data NotificationSendResponse: type: object properties: data: allOf: - $ref: "#/components/schemas/NotificationV1" - type: - object - "null" required: - data NotificationCreateRequest: type: object properties: type: type: string enum: - api_key_expiring - account_suspended - account_activated - portal_invitation - portal_signup_verification - magic_link_portal - magic_link_dashboard - email_verification - password_reset - welcome - email_change_verification - password_verification - account_invitation - organization_welcome - dashboard_user_welcome description: "Tipo de notificação (obrigatório): escolhe o modelo ativo da organização, ou o padrão da plataforma." recipient: type: string description: Endereço de destino (obrigatório) — um e-mail no canal `email`. channel: type: string enum: - email - in_app - webhook description: Canal de envio. Padrão `email`. portal_user_id: type: - string - "null" format: uuid description: Usuário do portal a que a notificação se destina; precisa ser da organização (senão, 404). resource_type: type: - string - "null" description: Tipo do registro relacionado. resource_id: type: - string - "null" format: uuid description: ID (UUID) do registro relacionado. scheduled_for: type: - string - "null" format: date-time description: Data e hora ISO 8601 para enviar, em vez de imediatamente. variables: type: object additionalProperties: anyOf: - type: string - type: number - type: boolean - type: "null" - type: "null" description: "Valores das variáveis do modelo: até 100, nomes com letras, dígitos, `_`, `.` ou `-`; valores texto (até 10.000 caracteres), número, booleano ou `null`." required: - type - recipient NotificationStatsResponse: type: object properties: data: type: object properties: total: type: integer description: Notificações criadas na janela. by_status: type: object additionalProperties: type: integer description: Contagem por status. by_channel: type: object additionalProperties: type: integer description: Contagem por canal. by_type: type: object additionalProperties: type: integer description: Contagem por tipo. delivery_rate: type: number description: (enviadas + entregues) / total, entre 0 e 1. read_rate: type: number description: lidas / total, entre 0 e 1. required: - total - by_status - by_channel - by_type - delivery_rate - read_rate required: - data ApiKeyV1: type: object properties: id: type: string format: uuid name: type: string description: type: - string - "null" source: type: string enum: - api - dashboard - manage description: "Onde a chave é usada: `api`, `dashboard` ou `manage`." prefix: type: string description: Início visível da chave (`kb_xxxxxxxx...`), para reconhecê-la sem o segredo. status: type: string enum: - active - disabled - revoked description: "`active`, `disabled` (pode ser reativada) ou `revoked` (definitivo)." notification_emails: type: array items: type: string description: "Quem recebe os avisos de expiração. Vazio: o criador." created_by_email: type: - string - "null" updated_by_email: type: - string - "null" enabled_by_email: type: - string - "null" disabled_by_email: type: - string - "null" revoked_by_email: type: - string - "null" created_at: type: string format: date-time updated_at: type: string format: date-time last_used_at: type: - string - "null" format: date-time enabled_at: type: - string - "null" format: date-time disabled_at: type: - string - "null" format: date-time revoked_at: type: - string - "null" format: date-time expires_at: type: - string - "null" format: date-time description: "Quando a chave expira (`null`: não expira)." rotated_at: type: - string - "null" format: date-time description: Quando a chave foi substituída por uma sucessora. required: - id - name - description - source - prefix - status - notification_emails - created_by_email - updated_by_email - enabled_by_email - disabled_by_email - revoked_by_email - created_at - updated_at - last_used_at - enabled_at - disabled_at - revoked_at - expires_at - rotated_at ApiKeyListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/ApiKeyV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta ApiKeyResponse: type: object properties: data: $ref: "#/components/schemas/ApiKeyV1" required: - data ApiKeyWithSecretV1: allOf: - $ref: "#/components/schemas/ApiKeyV1" - type: object properties: key: type: string description: O segredo em texto claro. Exibido somente nesta resposta — guarde-o agora. required: - key ApiKeyCreatedResponse: type: object properties: data: $ref: "#/components/schemas/ApiKeyWithSecretV1" required: - data ApiKeyRotatedV1: allOf: - $ref: "#/components/schemas/ApiKeyV1" - type: object properties: key: type: string description: O segredo em texto claro. Exibido somente nesta resposta — guarde-o agora. previous_key: type: object properties: id: type: string format: uuid rotated_at: type: string format: date-time grace_until: type: string format: date-time description: Fim do prazo de carência da chave anterior. required: - id - rotated_at - grace_until description: A chave substituída e até quando ela continua valendo. required: - key - previous_key ApiKeyRotatedResponse: type: object properties: data: $ref: "#/components/schemas/ApiKeyRotatedV1" required: - data ApiKeyCreateRequest: type: object properties: name: type: string minLength: 1 description: Nome da chave (obrigatório). description: type: - string - "null" source: type: string enum: - api - dashboard - manage description: Onde a chave será usada. Padrão `dashboard`. notification_emails: type: array items: type: string description: E-mails que recebem os avisos de expiração. expires_at: type: string format: date-time description: "Validade (data-hora ISO 8601 no futuro). Padrão: daqui a um ano." required: - name ApiKeyUpdateRequest: type: object properties: name: type: string minLength: 1 description: type: - string - "null" source: type: string enum: - api - dashboard - manage notification_emails: type: array items: type: string description: E-mails que recebem os avisos de expiração. expires_at: type: - string - "null" format: date-time description: Nova validade (ISO 8601); `null` remove a expiração. enabled: type: boolean description: "`false` desativa a chave; `true` reativa." ApiKeyRotateRequest: type: object properties: grace_days: type: integer minimum: 0 maximum: 30 description: Dias em que a chave anterior continua valendo (0 a 30, padrão 7). ExportV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid resource_type: type: string description: Recurso exportado. format: type: string enum: - csv - xlsx - json status: type: string enum: - pending - processing - completed - failed description: "`pending`, `processing`, `completed` ou `failed`." file_name: type: - string - "null" file_size_bytes: type: - integer - "null" total_rows: type: - integer - "null" filters: type: object additionalProperties: {} description: Filtros aplicados às linhas exportadas. error_message: type: - string - "null" download_available: type: boolean description: "`true` quando o arquivo pode ser baixado em `/download`." started_at: type: - string - "null" format: date-time completed_at: type: - string - "null" format: date-time expires_at: type: - string - "null" format: date-time description: Quando o arquivo deixa de estar disponível. created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - public_id - resource_type - format - status - file_name - file_size_bytes - total_rows - filters - error_message - download_available - started_at - completed_at - expires_at - created_at - updated_at ExportListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/ExportV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta ExportResponse: type: object properties: data: $ref: "#/components/schemas/ExportV1" required: - data ExportCreateRequest: type: object properties: resource_type: type: string enum: - portal_users description: "O que exportar. Hoje: `portal_users`." format: type: string enum: - csv - xlsx - json description: "`csv` (padrão), `xlsx` ou `json`." filters: type: object additionalProperties: {} description: Filtros opcionais das linhas exportadas. required: - resource_type ImportV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid resource_type: type: string description: Recurso importado. status: type: string enum: - pending - processing - completed - completed_with_errors - failed description: "`pending`, `processing`, `completed`, `completed_with_errors` ou `failed`." file_name: type: - string - "null" file_size_bytes: type: - integer - "null" total_rows: type: - integer - "null" processed_rows: type: integer success_count: type: integer error_count: type: integer errors: type: array items: {} description: Erros por linha registrados pelo processamento. error_message: type: - string - "null" started_at: type: - string - "null" format: date-time completed_at: type: - string - "null" format: date-time created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - public_id - resource_type - status - file_name - file_size_bytes - total_rows - processed_rows - success_count - error_count - errors - error_message - started_at - completed_at - created_at - updated_at ImportListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/ImportV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta ImportResponse: type: object properties: data: $ref: "#/components/schemas/ImportV1" required: - data ImportCreateRequest: type: object properties: resource_type: type: string enum: - portal_users description: "O que importar. Hoje: `portal_users`." file_name: type: string minLength: 1 description: "Nome original do arquivo, ex.: `usuarios.csv`." content_type: type: string description: Tipo do arquivo. Padrão `text/csv`. content_base64: type: string minLength: 1 description: O CSV codificado em base64. required: - resource_type - file_name - content_base64 BackupV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid type: type: string enum: - backup - restore description: "`backup` (cópia gerada) ou `restore` (restauração)." status: type: string enum: - pending - processing - completed - failed - canceled file_name: type: - string - "null" file_size_bytes: type: - integer - "null" resource_counts: type: object additionalProperties: type: number description: Quantidade de registros por recurso no arquivo. progress: type: integer description: Progresso de 0 a 100. current_resource: type: - string - "null" error_message: type: - string - "null" requested_by: type: - string - "null" description: Quem pediu (e-mail, ou `api:` para token de máquina). download_available: type: boolean description: "`true` quando o ZIP de um backup concluído pode ser baixado." started_at: type: - string - "null" format: date-time completed_at: type: - string - "null" format: date-time expires_at: type: - string - "null" format: date-time created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - public_id - type - status - file_name - file_size_bytes - resource_counts - progress - current_resource - error_message - requested_by - download_available - started_at - completed_at - expires_at - created_at - updated_at BackupListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/BackupV1" meta: $ref: "#/components/schemas/PaginationMeta" backup_allowed: type: boolean description: Se um novo backup pode ser pedido agora. next_backup_at: type: - string - "null" format: date-time description: Quando o próximo backup fica liberado (`null` se já está). required: - data - meta - backup_allowed - next_backup_at BackupResponse: type: object properties: data: $ref: "#/components/schemas/BackupV1" required: - data BackupRestoreRequest: type: object properties: backup_id: type: string format: uuid description: Backup concluído desta organização a restaurar. file_name: type: string description: Nome do arquivo `.zip`, junto com `content_base64`. content_base64: type: string description: O ZIP do backup em base64. DataPurgeCountsV1: type: object properties: counts: type: object properties: portal_users: type: integer people: type: integer usage_history: type: integer required: - portal_users - people - usage_history description: Registros por recurso, somando todos os workspaces. required: - counts DataPurgeCountsResponse: type: object properties: data: $ref: "#/components/schemas/DataPurgeCountsV1" required: - data DataPurgeRequest: type: object properties: resources: type: array items: type: string enum: - portal_users - people - usage_history minItems: 1 description: "O que apagar: `portal_users`, `people`, `usage_history`." confirm: type: string description: "Confirmação: o ID da organização, digitado de novo." required: - resources - confirm DataPurgeQueuedV1: type: object properties: job_id: type: string description: ID do job de limpeza. status: type: string enum: - queued resources: type: array items: type: string enum: - portal_users - people - usage_history required: - job_id - status - resources DataPurgeQueuedResponse: type: object properties: data: $ref: "#/components/schemas/DataPurgeQueuedV1" required: - data DataPurgeJobV1: type: object properties: job_id: type: string status: type: string description: "Estado do job na fila: `waiting`, `active`, `completed`, `failed`…" progress: type: number description: Progresso de 0 a 100. result: description: Resultado do job quando concluído (registros apagados por recurso). failed_reason: type: - string - "null" required: - job_id - status - progress - failed_reason DataPurgeJobResponse: type: object properties: data: $ref: "#/components/schemas/DataPurgeJobV1" required: - data MaintenanceUppercaseNamesV1: type: object properties: updated: type: integer description: Número de nomes alterados. required: - updated MaintenanceUppercaseNamesResponse: type: object properties: data: $ref: "#/components/schemas/MaintenanceUppercaseNamesV1" required: - data OrganizationSettingsV1: type: object properties: id: type: string format: uuid general: type: object properties: name: type: string support_email: type: string description: E-mail de suporte exibido aos clientes. timezone: type: string description: Fuso horário IANA (padrão `America/Sao_Paulo`). required: - name - support_email - timezone records: type: object properties: uppercase_names: type: boolean allow_edit_public_id: type: boolean allow_edit_document: type: boolean allow_create_customers: type: boolean allow_create_portal_users: type: boolean allow_edit_portal_user_email: type: boolean required: - uppercase_names - allow_edit_public_id - allow_edit_document - allow_create_customers - allow_create_portal_users - allow_edit_portal_user_email description: "Opções de cadastros: nomes em maiúsculas e o que o painel permite criar ou editar." required: - id - general - records OrganizationSettingsResponse: type: object properties: data: $ref: "#/components/schemas/OrganizationSettingsV1" required: - data OrganizationSettingsUpdateRequest: type: object properties: name: type: string minLength: 1 support_email: type: string format: email timezone: type: string description: "Fuso horário IANA, ex.: `America/Sao_Paulo`." crm_uppercase_names: type: boolean description: Salvar nomes em MAIÚSCULAS. crm_allow_edit_public_id: type: boolean crm_allow_edit_document: type: boolean crm_allow_create_customers: type: boolean crm_allow_create_portal_users: type: boolean description: Permitir criar usuários do portal pelo painel e por importação. crm_allow_edit_portal_user_email: type: boolean SystemUsageV1: type: object properties: start_date: type: string format: date end_date: type: string format: date metrics: type: array items: type: object properties: metric: type: string description: Identificador da métrica. current: type: - number - "null" description: Valor do dia mais recente do período. peak: type: - number - "null" description: Maior valor do período. series: type: array items: type: object properties: date: type: string format: date quantity: type: number required: - date - quantity required: - metric - current - peak - series last_updated_at: type: - string - "null" format: date-time required: - start_date - end_date - metrics - last_updated_at SystemUsageResponse: type: object properties: data: $ref: "#/components/schemas/SystemUsageV1" required: - data AiUsageV1: type: object properties: month_start: type: string format: date-time month_to_date: type: object properties: price_usd: type: - string - "null" turns: type: integer tokens: type: integer required: - price_usd - turns - tokens description: Acumulado do mês da organização. courtesy: type: object properties: in_force: type: boolean monthly_limit_usd: type: - string - "null" consumed_usd: type: - string - "null" valid_until: type: - string - "null" format: date required: - in_force - monthly_limit_usd - consumed_usd - valid_until description: Franquia de cortesia em vigor. org_cap_usd: type: - string - "null" description: Teto mensal da organização, quando houver. credit_balance_usd: type: string next_turn: type: object properties: allowed: type: boolean funded_by: type: - string - "null" code: type: - string - "null" required: - allowed - funded_by - code description: Se o próximo turno de IA é permitido e quem o financia. entitlement: type: object properties: has_plan: type: boolean monthly_limit_usd: type: - string - "null" required: - has_plan - monthly_limit_usd period: type: object properties: start_date: type: string format: date end_date: type: string format: date turns: type: integer prompt_tokens: type: integer completion_tokens: type: integer total_tokens: type: integer price_usd: type: string description: Preço em dólares, como texto decimal. required: - start_date - end_date - turns - prompt_tokens - completion_tokens - total_tokens - price_usd description: Totais do workspace no período. by_day: type: array items: type: object properties: date: type: string format: date turns: type: integer prompt_tokens: type: integer completion_tokens: type: integer total_tokens: type: integer price_usd: type: string description: Preço em dólares, como texto decimal. required: - date - turns - prompt_tokens - completion_tokens - total_tokens - price_usd recent: type: array items: type: object properties: id: type: string format: uuid workspace_id: type: - string - "null" format: uuid conversation_id: type: - string - "null" prompt_tokens: type: integer completion_tokens: type: integer total_tokens: type: integer price_usd: type: string funded_by: type: - string - "null" created_at: type: string format: date-time required: - id - workspace_id - conversation_id - prompt_tokens - completion_tokens - total_tokens - price_usd - funded_by - created_at required: - month_start - month_to_date - courtesy - org_cap_usd - credit_balance_usd - next_turn - entitlement - period - by_day - recent AiUsageResponse: type: object properties: data: $ref: "#/components/schemas/AiUsageV1" required: - data RateLimitsV1: type: object properties: config: type: object properties: get_requests_per_minute: type: integer get_requests_per_hour: type: integer mutate_requests_per_minute: type: integer mutate_requests_per_hour: type: integer burst_limit: type: integer burst_window_seconds: type: integer enabled: type: boolean required: - get_requests_per_minute - get_requests_per_hour - mutate_requests_per_minute - mutate_requests_per_hour - burst_limit - burst_window_seconds - enabled description: Limites em vigor. has_custom_config: type: boolean description: "`true` quando a organização tem configuração própria." defaults: type: object properties: get_requests_per_minute: type: integer get_requests_per_hour: type: integer mutate_requests_per_minute: type: integer mutate_requests_per_hour: type: integer burst_limit: type: integer burst_window_seconds: type: integer enabled: type: boolean required: - get_requests_per_minute - get_requests_per_hour - mutate_requests_per_minute - mutate_requests_per_hour - burst_limit - burst_window_seconds - enabled description: Padrões da plataforma. required: - config - has_custom_config - defaults RateLimitsResponse: type: object properties: data: $ref: "#/components/schemas/RateLimitsV1" required: - data PortalUserMappingV1: type: object properties: entity_type_id: type: string format: uuid tenant_id_field_key: type: string description: Campo da entidade que dá o ID do titular do usuário. email_field_key: type: string name_field_key: type: - string - "null" mapped_at: type: string mapped_by_email: type: - string - "null" last_synced_at: type: - string - "null" last_status: type: - string - "null" enum: - completed - error last_error: type: - string - "null" last_stats: type: - object - "null" properties: read: type: integer users_created: type: integer users_existing: type: integer users_linked: type: integer users_retenanted: type: integer skipped: type: integer required: - read - users_created - users_existing - users_linked - users_retenanted - skipped cascade_tenant_ids: type: boolean description: "A origem do ID do titular mudou: a próxima sincronização regrava o dos usuários existentes." required: - entity_type_id - tenant_id_field_key - email_field_key - name_field_key - mapped_at - mapped_by_email - last_synced_at - last_status - last_error - last_stats - cascade_tenant_ids PortalUserMappingStateV1: type: object properties: mapping: allOf: - $ref: "#/components/schemas/PortalUserMappingV1" - type: - object - "null" entities: type: array items: type: object properties: id: type: string format: uuid name: type: string identifier_field_key: type: - string - "null" owner_field_key: type: - string - "null" records_count: type: integer fields: type: array items: type: object properties: key: type: string name: type: string data_type: type: string semantic_role: type: - string - "null" required: - key - name - data_type - semantic_role required: - id - name - identifier_field_key - owner_field_key - records_count - fields description: Entidades do workspace que podem ser mapeadas, com seus campos. required: - mapping - entities PortalUserMappingGetResponse: type: object properties: data: $ref: "#/components/schemas/PortalUserMappingStateV1" required: - data PortalUserMappingSyncedV1: type: object properties: mapping: allOf: - $ref: "#/components/schemas/PortalUserMappingV1" - type: - object - "null" stats: type: - object - "null" properties: read: type: integer users_created: type: integer users_existing: type: integer users_linked: type: integer users_retenanted: type: integer skipped: type: integer required: - read - users_created - users_existing - users_linked - users_retenanted - skipped description: Resultado da sincronização feita agora. required: - mapping - stats PortalUserMappingUpdateResponse: type: object properties: data: $ref: "#/components/schemas/PortalUserMappingSyncedV1" required: - data PortalUserMappingDeletedV1: type: object properties: mapping: type: "null" deleted: type: boolean required: - mapping - deleted PortalUserMappingDeleteResponse: type: object properties: data: $ref: "#/components/schemas/PortalUserMappingDeletedV1" required: - data PortalUserMappingUpdateRequest: type: object properties: entity_type_id: type: string format: uuid description: A entidade cujos registros viram usuários do portal. tenant_id_field_key: type: string minLength: 1 maxLength: 200 email_field_key: type: string minLength: 1 maxLength: 200 name_field_key: type: - string - "null" maxLength: 200 required: - entity_type_id - tenant_id_field_key - email_field_key AssetV1: type: object properties: id: type: string format: uuid name: type: string description: Nome de exibição do arquivo (por padrão, o nome original, com a extensão). url: type: string description: "Link para quem pode abrir o arquivo: a URL do storage quando `public`, a rota do portal quando `restricted` (usuários do portal logados) e a rota do dashboard quando `private`." download_url: type: string description: Caminho da API que devolve o conteúdo do arquivo ao token, qualquer que seja a visibilidade. visibility: type: string enum: - public - restricted - private description: "Quem pode baixar: `public` (qualquer pessoa com o link), `restricted` (usuários logados no portal do workspace) ou `private` (só membros do dashboard). Arquivos novos começam `restricted`." content_type: type: string example: image/png size_bytes: type: integer description: Tamanho em bytes. kind: type: string enum: - image - document - other description: "`image`, `document` ou `other`, derivado do tipo do arquivo." alt_text: type: - string - "null" description: Texto alternativo de uma imagem (acessibilidade). source: type: string enum: - upload - chat - ai description: "Por onde o arquivo entrou: `upload` (dashboard ou API), `chat` (enviado no chat do construtor) ou `ai` (salvo pela IA do construtor)." created_by_email: type: - string - "null" description: E-mail de quem enviou o arquivo, quando conhecido. created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - name - url - download_url - visibility - content_type - size_bytes - kind - alt_text - source - created_by_email - created_at - updated_at AssetResponse: type: object properties: data: $ref: "#/components/schemas/AssetV1" required: - data AssetListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/AssetV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta AssetCreateRequest: type: object properties: name: type: string description: Nome de exibição, com a extensão (obrigatório). A extensão decide o tipo aceito quando `content_type` não vem. key: type: string description: O `key` devolvido por `POST /assets/presign`, depois de enviar o arquivo para a URL assinada. Envie `key` ou `content_base64`, nunca os dois. content_base64: type: string description: "O conteúdo do arquivo em base64, para arquivos pequenos: o corpo da requisição tem limite de 2 MB (cerca de 1,5 MB de arquivo). Para arquivos maiores, use `POST /assets/presign`." content_type: type: string description: "Tipo MIME. Quando omitido, é deduzido da extensão. Aceitos: imagens PNG, JPEG, GIF, WebP e AVIF; PDF, texto, CSV, Markdown, JSON, XML, Office e ZIP. SVG e HTML não são aceitos." alt_text: type: string description: Texto alternativo de uma imagem (acessibilidade). visibility: type: string enum: - public - restricted - private description: "Quem pode baixar: `public` (qualquer pessoa com o link), `restricted` (usuários logados no portal do workspace) ou `private` (só membros do dashboard). Arquivos novos começam `restricted`." required: - name AssetUpdateRequest: type: object properties: name: type: string description: Nome de exibição do arquivo (por padrão, o nome original, com a extensão). alt_text: type: - string - "null" description: Texto alternativo de uma imagem. Envie `null` para limpar. visibility: type: string enum: - public - restricted - private description: "Quem pode baixar: `public` (qualquer pessoa com o link), `restricted` (usuários logados no portal do workspace) ou `private` (só membros do dashboard). Arquivos novos começam `restricted`." AssetPresignRequest: type: object properties: filename: type: string description: Nome do arquivo com a extensão. content_type: type: string description: "Tipo MIME. Quando omitido, é deduzido da extensão. Aceitos: imagens PNG, JPEG, GIF, WebP e AVIF; PDF, texto, CSV, Markdown, JSON, XML, Office e ZIP. SVG e HTML não são aceitos." size: type: integer exclusiveMinimum: 0 description: Tamanho exato, em bytes, do arquivo que será enviado (máximo 25 MB). required: - filename - size AssetPresignResponse: type: object properties: data: type: object properties: url: type: string description: URL assinada e de curta duração para onde enviar o arquivo com `PUT`. method: type: string enum: - PUT headers: type: object additionalProperties: type: string description: Cabeçalhos que o `PUT` precisa levar exatamente como estão. key: type: string description: "Chave do arquivo no storage: envie em `POST /assets` para registrá-lo." content_type: type: string description: Tipo MIME resolvido para o arquivo. required: - url - method - headers - key - content_type required: - data DashboardUserUpsertResponse: type: object properties: data: $ref: "#/components/schemas/DashboardUserV1" matched_by: type: - string - "null" description: Chave que localizou o registro existente. `null` quando o registro foi criado. required: - data - matched_by DashboardUserUpsertRequest: type: object properties: email: type: string format: email description: E-mail do usuário. Além de campo do recurso, serve como chave natural da busca. name: type: string description: Nome do usuário (opcional — pode ser preenchido pelo usuário no primeiro acesso). external_id: type: string description: "Identificador externo do usuário, guardado como atributo do membro. Não define a identidade do usuário: ela é sempre resolvida pelo `email`." role_ids: type: array items: type: string format: uuid minItems: 1 description: Lista de UUIDs de papéis (`team_roles`) a atribuir ao usuário. Deve conter ao menos um item. permissions: type: array items: type: string description: Permissões ad-hoc adicionais (além das herdadas pelos papéis). Aceita os mesmos slugs de permissão. custom_metadata: type: - object - "null" additionalProperties: {} description: Metadados arbitrários definidos pelo cliente (chave/valor). id: type: string format: uuid description: UUID do registro. Usado apenas para localizá-lo — nunca é gravado. public_id: type: string format: uuid description: UUID público do registro, usado para localizá-lo. TeamRoleUpsertResponse: type: object properties: data: $ref: "#/components/schemas/TeamRoleV1" matched_by: type: - string - "null" description: Chave que localizou o registro existente. `null` quando o registro foi criado. required: - data - matched_by TeamRoleUpsertRequest: type: object properties: name: type: string minLength: 1 description: Nome do papel (exibido na interface). slug: type: string pattern: ^[a-z][a-z0-9_]*$ description: "Slug estável usado para referenciar o papel (ex.: `support_manager`)." example: portal_manager description: type: string description: Descrição opcional do que o papel concede. permissions: type: array items: type: string description: Lista de slugs de permissão concedidas pelo papel. is_active: type: boolean description: Indica se o papel está ativo e pode ser atribuído. external_id: type: string description: Identificador no seu sistema externo, para idempotência/sincronização. custom_metadata: type: - object - "null" additionalProperties: {} description: Metadados arbitrários definidos pelo cliente (chave/valor). id: type: string format: uuid description: UUID do registro. Usado apenas para localizá-lo — nunca é gravado. public_id: type: string format: uuid description: UUID público do registro, usado para localizá-lo. parameters: {} securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: "Envie o cabeçalho `Authorization: Bearer `. O token é um access token RS256 emitido pelo Authorization Server da Kobana (`account.kobana.com.br`), com `aud` igual a `https://api.dashboards.kobana.com.br` e `exp` obrigatória. A claim `org` (a conta Kobana) é o que escopa os dados e também é obrigatória; `sub` é a **pessoa** e serve para auditoria. Esta API só verifica o token — não emite nenhum. O claim `scope` também é verificado: `GET` exige `read`, `write` ou `all`, e qualquer outro método exige `write` ou `all` — sem isso a resposta é `403 insufficient_scope`, com `{ required, granted }` em `details`. Um token emitido a uma **pessoa** (`src` `user` ou `oauth`) também fica limitado ao que ela pode fazer no dashboard: a operação exige a permissão correspondente do papel dela (senão `403 insufficient_permission`, com `{ required }` em `details`), e quem não é membro ativo da organização é recusado. Um token de pessoa que o app não consegue identificar pelo `sub` retorna `401 invalid_token`. Tokens de máquina (`src` `system` ou `api`) agem pela organização." paths: /v1/organization: get: tags: - Organização summary: Obter organização atual description: Retorna os dados da organização à qual o token autenticado pertence. Não há parâmetro `:id` — a organização é sempre resolvida a partir da chave da API. security: - bearerAuth: [] responses: "200": description: Detalhe da organização atual. content: application/json: schema: $ref: "#/components/schemas/OrganizationResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-organization parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier patch: tags: - Organização summary: Atualizar organização atual description: Atualiza o perfil cadastral da organização autenticada. Apenas os campos abaixo podem ser modificados — identidade (`id`, `external_id`, `status`) não é alterável por este endpoint. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/OrganizationUpdateRequest" responses: "200": description: Organização atualizada. content: application/json: schema: $ref: "#/components/schemas/OrganizationResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-organization parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/me: get: tags: - Organização summary: Identidade do token atual description: "Retorna quem está por trás do token Bearer: a pessoa (`user`, `null` para um token de máquina), a organização e os escopos, o nível de acesso e a expiração do próprio token. Serve para validar a credencial configurada numa integração. Nunca devolve o token, hashes ou chaves." security: - bearerAuth: [] responses: "200": description: Identidade do token autenticado. content: application/json: schema: $ref: "#/components/schemas/MeResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-me parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/portal_users: get: tags: - Usuários do Portal summary: Listar usuários do portal description: Retorna os usuários do portal do workspace, com paginação. Campos sensíveis (senha, tokens) nunca são expostos. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Página (começa em 1). Padrão: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Itens por página. Padrão: `20`. Máximo: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Campo de ordenação. Padrão depende do recurso. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Direção da ordenação. Padrão: `desc`." required: false name: sort_order in: query - schema: type: string description: Restringe aos usuários de um ID do titular (comparação exata). required: false name: tenant_id in: query - schema: type: string enum: - active - pending_verification - pending_invitation - suspended - locked description: "Filtra por status: `active`, `pending_invitation`, `pending_verification`, `suspended` ou `locked`." required: false name: status in: query - schema: type: string description: Busca por trecho do e-mail. required: false name: email in: query - schema: type: string description: Filtra pelo `external_id` exato. required: false name: external_id in: query - schema: type: string enum: - "true" - "false" description: Filtra por `sso_only` (`true` ou `false`). required: false name: sso_only in: query - schema: type: string description: Data de criação inicial do intervalo (YYYY-MM-DD). required: false name: created_after in: query - schema: type: string description: Data de criação final do intervalo (YYYY-MM-DD). required: false name: created_before in: query - schema: type: string description: Último acesso a partir desta data (ISO 8601). required: false name: last_login_after in: query - schema: type: string description: Último acesso até esta data (ISO 8601). required: false name: last_login_before in: query - schema: type: string format: uuid description: Filtra por UUID da pessoa associada. required: false name: person_id in: query - schema: type: string description: Filtra por CPF/CNPJ da pessoa (exato). required: false name: person_document_number in: query - schema: type: string description: Filtra por nome da pessoa (busca parcial, sem distinção de maiúsculas). required: false name: person_name_contains in: query - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Lista paginada de usuários do portal. content: application/json: schema: $ref: "#/components/schemas/PortalUserListResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-portal-users post: tags: - Usuários do Portal summary: Criar (convidar) usuário do portal description: Cria o usuário no workspace com status `pending_invitation` e envia o e-mail de convite. O convite expira em 7 dias. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PortalUserCreateRequest" responses: "201": description: Convite criado e e-mail enfileirado para envio. content: application/json: schema: $ref: "#/components/schemas/PortalUserResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: Já existe um usuário ou convite para este e-mail no workspace. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-portal-users parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/portal_users/invite: post: tags: - Usuários do Portal summary: Convidar usuário do portal (verbo) description: Equivalente ao `POST /portal_users`. Disponível como rota de verbo para SDKs que preferem URLs descritivas. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PortalUserCreateRequest" responses: "201": description: Convite criado e e-mail enfileirado para envio. content: application/json: schema: $ref: "#/components/schemas/PortalUserResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: Já existe um usuário ou convite para este e-mail no workspace. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-portal-users-invite parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/portal_users/{id}: get: tags: - Usuários do Portal summary: Obter usuário do portal description: O parâmetro `{id}` aceita o UUID ou o `external_id` do usuário. security: - bearerAuth: [] parameters: - schema: type: string description: UUID do usuário do portal ou seu `external_id`. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Detalhe do usuário do portal. content: application/json: schema: $ref: "#/components/schemas/PortalUserResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-portal-users-id patch: tags: - Usuários do Portal summary: Atualizar usuário do portal description: "Atualiza `email`, `tenant_id`, `external_id`, `sso_only`, `status` e `custom_metadata`. Transições de status permitidas: `active` ↔ `suspended`." security: - bearerAuth: [] parameters: - schema: type: string description: UUID do usuário do portal ou seu `external_id`. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/PortalUserUpdateRequest" responses: "200": description: Usuário atualizado. content: application/json: schema: $ref: "#/components/schemas/PortalUserResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: Já existe um usuário ou convite para este e-mail no workspace. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-portal-users-id delete: tags: - Usuários do Portal summary: Remover usuário do portal description: Convites pendentes são removidos definitivamente; os demais usuários são suspensos. security: - bearerAuth: [] parameters: - schema: type: string description: UUID do usuário do portal ou seu `external_id`. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Confirmação de remoção. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-portal-users-id /v1/portal_users/{id}/email-preview: get: tags: - Usuários do Portal summary: Pré-visualizar e-mail do usuário do portal description: Retorna o assunto e a mensagem do e-mail de convite ou verificação que seria enviado ao usuário, sem disparar o envio. Disponível apenas para usuários `pending_invitation` ou `pending_verification`. security: - bearerAuth: [] parameters: - schema: type: string description: UUID do usuário do portal ou seu `external_id`. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Pré-visualização do e-mail. content: application/json: schema: $ref: "#/components/schemas/PortalUserEmailPreviewResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-portal-users-id-email-preview /v1/portal_users/{id}/resend: post: tags: - Usuários do Portal summary: Reenviar e-mail de convite ou verificação description: Reenvia o e-mail de convite (para `pending_invitation`, com rotação de token) ou de verificação (para `pending_verification`). Demais status retornam 400. security: - bearerAuth: [] parameters: - schema: type: string description: UUID do usuário do portal ou seu `external_id`. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: E-mail reenviado. content: application/json: schema: $ref: "#/components/schemas/PortalUserResendResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-portal-users-id-resend /v1/dashboard_users: get: tags: - Administração da Conta summary: Listar usuários do dashboard description: Retorna uma lista paginada dos usuários do dashboard (membros do time) da organização atual. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Página (começa em 1). Padrão: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Itens por página. Padrão: `20`. Máximo: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Campo de ordenação. Padrão depende do recurso. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Direção da ordenação. Padrão: `desc`." required: false name: sort_order in: query - schema: type: string description: Busca textual por nome ou e-mail. required: false name: search in: query - schema: type: string enum: - all - active - pending_invitation - suspended description: "Filtra por status: `all` (padrão), `active`, `pending_invitation` ou `suspended`." required: false name: status in: query - schema: type: string description: Filtra pelos usuários que possuem o papel informado (slug do papel). required: false name: role in: query - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Lista paginada de usuários do dashboard. content: application/json: schema: $ref: "#/components/schemas/DashboardUserListResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-dashboard-users post: tags: - Administração da Conta summary: Convidar usuário do dashboard description: Convida um novo membro para o time da organização. É obrigatório informar `email` e ao menos um papel em `role_ids`. O usuário recebe um convite por e-mail e entra com status `pending_invitation`. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/DashboardUserCreateRequest" responses: "201": description: Usuário convidado. content: application/json: schema: $ref: "#/components/schemas/DashboardUserResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Dados inválidos. Com o código `IDENTITY_CONFLICT`, o `external_id` informado é o identificador de outra identidade, com outro e-mail. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-dashboard-users parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier put: tags: - Administração da Conta summary: Cria ou atualiza um usuário do painel description: Localiza o usuário por `id`, `public_id`, `external_id` ou `email` — este último é único por organização. Encontrando, atualiza; caso contrário, cria e devolve `201`. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/DashboardUserUpsertRequest" responses: "200": description: Registro atualizado. content: application/json: schema: $ref: "#/components/schemas/DashboardUserUpsertResponse" "201": description: Registro criado. content: application/json: schema: $ref: "#/components/schemas/DashboardUserUpsertResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Dados inválidos. Com o código `IDENTITY_CONFLICT`, o `external_id` informado é o identificador de outra identidade, com outro e-mail. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-dashboard-users parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/dashboard_users/{id}: get: tags: - Administração da Conta summary: Obter usuário do dashboard security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: UUID do usuário do dashboard. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Detalhe do usuário do dashboard. content: application/json: schema: $ref: "#/components/schemas/DashboardUserResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-dashboard-users-id patch: tags: - Administração da Conta summary: Atualizar usuário do dashboard description: Atualiza nome, foto, status, permissões e/ou papéis do usuário. Apenas os campos enviados são alterados. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: UUID do usuário do dashboard. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/DashboardUserUpdateRequest" responses: "200": description: Usuário atualizado. content: application/json: schema: $ref: "#/components/schemas/DashboardUserResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-dashboard-users-id delete: tags: - Administração da Conta summary: Remover usuário do dashboard description: Remove o usuário do dashboard da organização. Ação irreversível — o usuário precisa ser convidado novamente para recuperar o acesso. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: UUID do usuário do dashboard. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Usuário removido. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-dashboard-users-id /v1/team_roles: get: tags: - Administração da Conta summary: Listar papéis do time description: Retorna a lista paginada de papéis (roles) configurados para o time da organização. Inclui tanto papéis de sistema (`is_system = true`) quanto papéis customizados. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Página (começa em 1). Padrão: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Itens por página. Padrão: `20`. Máximo: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Campo de ordenação. Padrão depende do recurso. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Direção da ordenação. Padrão: `desc`." required: false name: sort_order in: query - schema: type: string description: Busca textual por nome ou slug. required: false name: search in: query - schema: type: - boolean - "null" description: Filtra por papéis ativos (`true`) ou inativos (`false`). required: false name: is_active in: query - schema: type: - boolean - "null" description: Filtra por papéis de sistema (`true`) ou customizados (`false`). required: false name: is_system in: query - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Lista paginada de papéis. content: application/json: schema: $ref: "#/components/schemas/TeamRoleListResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-team-roles post: tags: - Administração da Conta summary: Criar papel customizado description: Cria um papel customizado. O `slug` deve começar com letra minúscula e conter apenas letras minúsculas, números e `_`. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/TeamRoleCreateRequest" responses: "201": description: Papel criado. content: application/json: schema: $ref: "#/components/schemas/TeamRoleResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-team-roles parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier put: tags: - Administração da Conta summary: Cria ou atualiza um papel de equipe description: Localiza o papel por `id`, `public_id` ou `external_id`. O `slug` não tem restrição de unicidade e por isso **não** identifica um registro. Encontrando, atualiza; caso contrário, cria e devolve `201`. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/TeamRoleUpsertRequest" responses: "200": description: Registro atualizado. content: application/json: schema: $ref: "#/components/schemas/TeamRoleUpsertResponse" "201": description: Registro criado. content: application/json: schema: $ref: "#/components/schemas/TeamRoleUpsertResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-team-roles parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/team_roles/{id}: get: tags: - Administração da Conta summary: Obter papel security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: UUID do papel. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Detalhe do papel. content: application/json: schema: $ref: "#/components/schemas/TeamRoleResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-team-roles-id patch: tags: - Administração da Conta summary: Atualizar papel description: Atualiza os campos do papel. Apenas os campos enviados são alterados. Papéis de sistema têm restrições adicionais. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: UUID do papel. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/TeamRoleUpdateRequest" responses: "200": description: Papel atualizado. content: application/json: schema: $ref: "#/components/schemas/TeamRoleResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-team-roles-id delete: tags: - Administração da Conta summary: Remover papel description: Realiza soft delete do papel. Papéis de sistema (`is_system = true`) não podem ser removidos. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: UUID do papel. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Papel removido. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-team-roles-id /v1/workspaces: get: tags: - Workspaces summary: Listar workspaces description: Lista os workspaces da organização que você pode abrir, com o seu papel em cada um — os mesmos do seletor do dashboard. Um token de máquina vê todos os workspaces da organização. Não exige `X-Workspace-Id`. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Página (começa em 1). Padrão: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Itens por página. Padrão: `20`. Máximo: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Campo de ordenação. Padrão depende do recurso. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Direção da ordenação. Padrão: `desc`." required: false name: sort_order in: query - schema: type: string description: Trecho do nome do workspace, sem diferenciar maiúsculas. required: false name: search in: query - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Página de workspaces. content: application/json: schema: $ref: "#/components/schemas/WorkspaceListResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-workspaces post: tags: - Workspaces summary: Criar workspace description: "Cria um workspace vazio na organização. A pessoa do token vira dona dele. Criado por um token de máquina, o workspace fica sem dono: os donos da organização o recebem no próximo login, e `PUT /dashboard_users/{id}/workspaces` o concede a outros membros." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/WorkspaceWriteRequest" responses: "201": description: Workspace criado. content: application/json: schema: $ref: "#/components/schemas/WorkspaceResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-workspaces parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/workspaces/import: post: tags: - Workspaces summary: Importar workspace description: Restaura um arquivo de `GET /workspaces/{id}/export` em um workspace NOVO, cujo dono é a pessoa do token. Responde o que não pôde ser trazido de volta (`warnings`) para terminar à mão. Exige um token de pessoa (um token de máquina recebe 403) com as permissões de criar workspaces, configurar o portal e criar fontes de dados. As entidades do arquivo passam pelas mesmas validações de quando são criadas uma a uma (chaves, expressões, limite de campos do workspace). O corpo é limitado a 2 MB. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/WorkspaceImportRequest" responses: "201": description: Workspace importado. content: application/json: schema: $ref: "#/components/schemas/WorkspaceImportResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: O arquivo não é uma exportação de workspace válida (`INVALID_WORKSPACE_FILE`). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-workspaces-import parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/workspaces/{id}: get: tags: - Workspaces summary: Consultar workspace description: Retorna um workspace que você pode abrir. Um workspace sem acesso concedido responde 404. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) do workspace. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Workspace encontrado. content: application/json: schema: $ref: "#/components/schemas/WorkspaceResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-workspaces-id patch: tags: - Workspaces summary: Renomear workspace description: Renomeia o workspace. Só os donos do workspace podem (403 para um membro comum). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) do workspace. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/WorkspaceWriteRequest" responses: "200": description: Workspace renomeado. content: application/json: schema: $ref: "#/components/schemas/WorkspaceResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-workspaces-id delete: tags: - Workspaces summary: Excluir workspace description: "Exclui o workspace (exclusão lógica), só para os donos dele: o portal sai do ar, os conectores param de sincronizar e os membros perdem o acesso. O último workspace da organização não pode ser excluído." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) do workspace. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Workspace excluído. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: É o último workspace da organização (`WORKSPACE_LAST`). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-workspaces-id /v1/workspaces/{id}/usage: get: tags: - Workspaces summary: Consultar o conteúdo do workspace description: Conta o que a exclusão do workspace esconderia — o mesmo resumo do diálogo de exclusão do dashboard. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) do workspace. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Contagens do workspace. content: application/json: schema: $ref: "#/components/schemas/WorkspaceUsageResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-workspaces-id-usage /v1/workspaces/{id}/export: get: tags: - Workspaces summary: Exportar workspace description: Baixa a configuração do workspace (construtor do portal, acesso e configurações do portal, mapeamento de usuários, conectores e entidades) como um arquivo JSON, só para os donos dele. Segredos e dados ficam de fora. A resposta é o próprio arquivo, sem envelope `data`; envie-o como `data` em `POST /workspaces/import`. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) do workspace. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: "Arquivo de exportação (`Content-Disposition: attachment`)." content: application/json: schema: $ref: "#/components/schemas/WorkspaceExportFile" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-workspaces-id-export /v1/dashboard_users/{id}/workspaces: get: tags: - Administração da Conta summary: Consultar os workspaces de um membro description: Lista todos os workspaces da organização, marcando os que o membro acessa — também é a lista do que pode ser concedido. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) do membro da equipe (usuário do dashboard). required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Workspaces da organização com o acesso do membro. content: application/json: schema: $ref: "#/components/schemas/WorkspaceGrantListResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-dashboard-users-id-workspaces put: tags: - Administração da Conta summary: Definir os workspaces de um membro description: Substitui o conjunto de workspaces do membro. Ninguém altera o próprio acesso (400), só um dono altera o acesso de um dono, e só um dono concede ou revoga um workspace que ele mesmo não acessa (403). Um token de máquina pode conceder qualquer workspace, mas nunca altera o acesso de um dono. Tirar o último dono de um workspace responde 403. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) do membro da equipe (usuário do dashboard). required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/WorkspaceGrantReplaceRequest" responses: "200": description: Workspaces da organização com o acesso do membro. content: application/json: schema: $ref: "#/components/schemas/WorkspaceGrantListResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-dashboard-users-id-workspaces /v1/dashboard_users/{id}/resend: post: tags: - Administração da Conta summary: Reenviar convite de membro description: Reenvia o e-mail de convite, com um novo link de acesso, a um membro cujo convite ainda está pendente. Limitado a 5 envios por hora por destinatário (429 acima disso). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) do membro da equipe (usuário do dashboard). required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Convite reenviado. content: application/json: schema: $ref: "#/components/schemas/DashboardUserResendResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: O membro não tem convite pendente (`INVALID_STATUS`). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "502": description: Não foi possível enviar o e-mail (`EMAIL_ERROR`). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-dashboard-users-id-resend /v1/permissions: get: tags: - Administração da Conta summary: Listar permissões description: Catálogo das permissões do dashboard que um membro ou um papel da equipe pode ter, agrupadas por recurso — o vocabulário de `permissions` em `/dashboard_users` e `/team_roles`. security: - bearerAuth: [] responses: "200": description: Grupos de permissões. content: application/json: schema: $ref: "#/components/schemas/PermissionCatalogResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-permissions parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/data_sources: get: tags: - Fontes de Dados summary: Listar fontes de dados description: "Fontes de dados do workspace — APIs OpenAPI, servidores MCP e bancos somente leitura —, das mais novas para as mais antigas. Os segredos nunca são devolvidos. Para criar uma fonte, use a rota do tipo: `/data_sources/openapi`, `/mcp`, `/database` ou `/catalog`." security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Página (começa em 1). Padrão: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Itens por página. Padrão: `20`. Máximo: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Campo de ordenação. Padrão depende do recurso. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Direção da ordenação. Padrão: `desc`." required: false name: sort_order in: query - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Página de fontes de dados. content: application/json: schema: $ref: "#/components/schemas/DataSourceListResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-data-sources /v1/data_sources/catalog: get: tags: - Fontes de Dados summary: Listar produtos do catálogo Kobana description: Produtos Kobana que podem ser conectados como fonte de dados só com um token. Lista completa, sem paginação. security: - bearerAuth: [] responses: "200": description: Produtos do catálogo. content: application/json: schema: $ref: "#/components/schemas/DataSourceCatalogResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-data-sources-catalog parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier post: tags: - Fontes de Dados summary: Conectar produto Kobana description: Salva uma fonte OpenAPI a partir da spec do produto que acompanha a aplicação e testa a conexão. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/DataSourceCatalogConnectRequest" responses: "201": description: Fonte criada, com o resultado do teste de conexão. content: application/json: schema: $ref: "#/components/schemas/DataSourceCreatedResponse" "400": description: Corpo que não é JSON, ou campo com tipo errado. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: Já existe uma fonte de dados com este nome no workspace. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-data-sources-catalog parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/data_sources/openapi: post: tags: - Fontes de Dados summary: Criar fonte OpenAPI description: Salva uma API descrita por uma spec OpenAPI, importa suas operações e testa a conexão. A spec vai como texto em `spec`; o certificado mTLS, em base64 em `certificate`. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/DataSourceOpenApiCreateRequest" responses: "201": description: Fonte criada, com o resultado do teste de conexão. content: application/json: schema: $ref: "#/components/schemas/DataSourceCreatedResponse" "400": description: Corpo que não é JSON, ou campo com tipo errado. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: Já existe uma fonte de dados com este nome no workspace. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-data-sources-openapi parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/data_sources/openapi/analyze: post: tags: - Fontes de Dados summary: Analisar spec OpenAPI description: Lê a spec e devolve o que seria importado — título, servidores, esquemas de segurança, autenticação sugerida e operações — sem salvar nada. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/DataSourceSpecRequest" responses: "200": description: Análise da spec. content: application/json: schema: $ref: "#/components/schemas/DataSourceSpecAnalysisResponse" "400": description: Corpo que não é JSON, ou campo com tipo errado. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-data-sources-openapi-analyze parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/data_sources/mcp: post: tags: - Fontes de Dados summary: Criar fonte MCP description: Salva um servidor MCP. Sem OAuth, conecta e descobre as tools na hora; com OAuth, devolve `authorization_url`, que uma pessoa logada no dashboard precisa abrir no navegador para concluir. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/DataSourceMcpCreateRequest" responses: "201": description: Fonte criada, com o resultado do teste de conexão. content: application/json: schema: $ref: "#/components/schemas/DataSourceMcpCreatedResponse" "400": description: Corpo que não é JSON, ou campo com tipo errado. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: Já existe uma fonte de dados com este nome no workspace. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-data-sources-mcp parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/data_sources/database: post: tags: - Fontes de Dados summary: Criar fonte de banco de dados description: Salva um banco somente leitura (PostgreSQL, MySQL, MariaDB, SQL Server ou MongoDB), conecta e cataloga as tabelas ou coleções. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/DataSourceDatabaseCreateRequest" responses: "201": description: Fonte criada, com o resultado do teste de conexão. content: application/json: schema: $ref: "#/components/schemas/DataSourceCreatedResponse" "400": description: Corpo que não é JSON, ou campo com tipo errado. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: Já existe uma fonte de dados com este nome no workspace. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-data-sources-database parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/data_sources/test: post: tags: - Fontes de Dados summary: Testar conexão antes de salvar description: Testa uma conexão ainda não salva. Informe `kind` (`openapi`, `mcp`, `database` ou `catalog`) e o corpo da rota de criação correspondente. Nada é persistido. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/DataSourceDraftTestRequest" responses: "200": description: Resultado do teste de conexão. content: application/json: schema: $ref: "#/components/schemas/DataSourceDraftTestResponse" "400": description: Corpo que não é JSON, ou campo com tipo errado. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-data-sources-test parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/data_sources/{id}: get: tags: - Fontes de Dados summary: Consultar fonte de dados description: A fonte de dados e suas operações (endpoints, tools ou tabelas que ela pode ler). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID da fonte de dados (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Fonte de dados com as operações. content: application/json: schema: $ref: "#/components/schemas/DataSourceDetailResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-data-sources-id patch: tags: - Fontes de Dados summary: Atualizar fonte de dados description: Atualiza nome, `is_active` e os campos de conexão do tipo da fonte. Campos secretos em branco mantêm os guardados. Uma fonte OpenAPI recebe um novo certificado em `certificate`. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID da fonte de dados (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/DataSourceUpdateRequest" responses: "200": description: Fonte de dados atualizada. content: application/json: schema: $ref: "#/components/schemas/DataSourceResponse" "400": description: Corpo que não é JSON, ou campo com tipo errado. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: Já existe uma fonte de dados com este nome no workspace. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-data-sources-id delete: tags: - Fontes de Dados summary: Excluir fonte de dados description: Remove a fonte, suas operações e a agenda de sincronização. As entidades alimentadas por ela deixam de sincronizar. Não pode ser desfeito. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID da fonte de dados (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Fonte excluída. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-data-sources-id /v1/data_sources/{id}/test: post: tags: - Fontes de Dados summary: Testar fonte de dados description: Testa a fonte salva e registra o resultado (status, último erro). Num servidor MCP, também atualiza a lista de tools. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID da fonte de dados (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Resultado do teste de conexão. content: application/json: schema: $ref: "#/components/schemas/DataSourceTestResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-data-sources-id-test /v1/data_sources/{id}/sync: post: tags: - Fontes de Dados summary: Sincronizar fonte de dados description: Enfileira a sincronização de todas as entidades alimentadas pela fonte. A execução é assíncrona. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID da fonte de dados (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: required: false content: application/json: schema: $ref: "#/components/schemas/DataSourceSyncRequest" responses: "202": description: Sincronização enfileirada. content: application/json: schema: $ref: "#/components/schemas/DataSourceSyncResponse" "400": description: Corpo que não é JSON, ou campo com tipo errado. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: "Limite excedido: o de requisições da API, ou o de sincronizações enfileiradas pela organização (60 por hora, somando todas as fontes de dados) — código `rate_limited`. Espere o tempo indicado em `Retry-After` e tente de novo." headers: Retry-After: description: Segundos até a organização poder enfileirar outra sincronização. schema: type: integer content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-data-sources-id-sync /v1/data_sources/{id}/schedule: put: tags: - Fontes de Dados summary: Agendar sincronização da fonte description: "Define com que frequência a fonte sincroniza: `{ cron, timezone }`, ou `{ cron: null }` para só sob demanda. Devolve as próximas execuções." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID da fonte de dados (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/DataSourceScheduleRequest" responses: "200": description: Agenda salva. content: application/json: schema: $ref: "#/components/schemas/DataSourceScheduleResponse" "400": description: Corpo que não é JSON, ou campo com tipo errado. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-data-sources-id-schedule /v1/data_sources/{id}/spec: put: tags: - Fontes de Dados summary: Substituir spec da fonte description: "Troca a spec OpenAPI e ressincroniza as operações: as que mantêm a chave mantêm suas configurações; as que sumiram da spec são removidas." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID da fonte de dados (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/DataSourceSpecRequest" responses: "200": description: Spec substituída, com os avisos da análise. content: application/json: schema: $ref: "#/components/schemas/DataSourceSpecResponse" "400": description: Corpo que não é JSON, ou campo com tipo errado. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-data-sources-id-spec /v1/data_sources/{id}/authorize: post: tags: - Fontes de Dados summary: Autorizar fonte MCP description: Reinicia a autorização OAuth de um servidor MCP. Devolve `authorization_url` para uma pessoa logada no dashboard abrir no navegador, ou `null` e o teste de conexão quando os tokens guardados ainda funcionam. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID da fonte de dados (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: URL de autorização ou resultado do teste. content: application/json: schema: $ref: "#/components/schemas/DataSourceAuthorizeResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-data-sources-id-authorize /v1/data_sources/{id}/logs: get: tags: - Fontes de Dados summary: Listar log de requisições da fonte description: Chamadas que a fonte fez (requisições HTTP, consultas ao banco), das mais novas para as mais antigas, sem cabeçalhos nem corpos. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID da fonte de dados (UUID). required: true name: id in: path - schema: type: integer minimum: 1 description: "Página (começa em 1). Padrão: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Itens por página. Padrão: `20`. Máximo: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Campo de ordenação. Padrão depende do recurso. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Direção da ordenação. Padrão: `desc`." required: false name: sort_order in: query - schema: type: string description: Método HTTP (GET, POST…). required: false name: method in: query - schema: type: string enum: - "true" - "false" description: "`true` só as chamadas bem-sucedidas, `false` só as que falharam." required: false name: success in: query - schema: type: string description: Trecho do endpoint, sem diferenciar maiúsculas. required: false name: search in: query - schema: type: string format: date description: A partir deste dia (YYYY-MM-DD, UTC), inclusive. required: false name: date_from in: query - schema: type: string format: date description: Até este dia (YYYY-MM-DD, UTC), inclusive. required: false name: date_to in: query - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Página do log de requisições. content: application/json: schema: $ref: "#/components/schemas/DataSourceRequestLogListResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-data-sources-id-logs /v1/data_sources/{id}/logs/{log_id}: get: tags: - Fontes de Dados summary: Consultar requisição da fonte description: "Uma chamada inteira: cabeçalhos e corpos da requisição e da resposta, com segredos mascarados." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID da fonte de dados (UUID). required: true name: id in: path - schema: type: string format: uuid description: ID da entrada do log de requisições. required: true name: log_id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Entrada do log de requisições. content: application/json: schema: $ref: "#/components/schemas/DataSourceRequestLogResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-data-sources-id-logs-log-id /v1/data_sources/{id}/operations/{operation_id}: patch: tags: - Fontes de Dados summary: Ligar ou desligar operação da fonte description: Liga ou desliga uma operação da fonte (`enabled`). Operações desligadas não alimentam entidades. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID da fonte de dados (UUID). required: true name: id in: path - schema: type: string format: uuid description: ID da operação da fonte. required: true name: operation_id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/DataSourceOperationUpdateRequest" responses: "200": description: Operação atualizada. content: application/json: schema: $ref: "#/components/schemas/DataSourceOperationResponse" "400": description: Corpo que não é JSON, ou campo com tipo errado. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-data-sources-id-operations-operation-id /v1/entities: get: tags: - Entidades summary: Listar entidades description: Todas as entidades do workspace, com campos, origem e estado da sincronização, ordenadas pelo nome. Sem paginação. security: - bearerAuth: [] responses: "200": description: Entidades do workspace. content: application/json: schema: $ref: "#/components/schemas/EntityListResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-entities parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier post: tags: - Entidades summary: Criar entidade description: Registra uma entidade a partir de uma operação de leitura (ou consulta SQL) da fonte de dados com os campos escolhidos, e enfileira a primeira sincronização completa. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/EntityCreateRequest" responses: "201": description: Entidade criada. content: application/json: schema: $ref: "#/components/schemas/EntityResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: "Conflito: chave já usada no workspace, ou a entidade é lida por uma relação." content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-entities parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/entities/preview: post: tags: - Entidades summary: Prévia de uma origem description: Chama a operação de leitura escolhida (ou roda a consulta SQL) e devolve a amostra com a entidade inferida dela. Nada é gravado; a chamada fica no log de requisições do conector. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/EntityPreviewRequest" responses: "200": description: Amostra e entidade inferida. content: application/json: schema: $ref: "#/components/schemas/EntityPreviewResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-entities-preview parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/entities/join: post: tags: - Entidades summary: Criar entidade de relação description: Registra uma entidade que relaciona duas outras (join) com os campos escolhidos de cada uma, e enfileira a primeira sincronização. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/EntityJoinRequest" responses: "201": description: Entidade criada. content: application/json: schema: $ref: "#/components/schemas/EntityResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: "Conflito: chave já usada no workspace, ou a entidade é lida por uma relação." content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-entities-join parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/entities/join/preview: post: tags: - Entidades summary: Prévia de uma relação description: Como duas entidades casam nos campos informados (contagens) e as primeiras linhas combinadas, antes de salvar a relação. Lê só os registros já sincronizados. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/EntityJoinSpecV1" responses: "200": description: Prévia da relação. content: application/json: schema: $ref: "#/components/schemas/EntityJoinPreviewResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-entities-join-preview parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/entities/{id}: get: tags: - Entidades summary: Consultar entidade description: Uma entidade com campos, origem, modo de sincronização, campo do titular e estado da sincronização. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) da entidade. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: A entidade. content: application/json: schema: $ref: "#/components/schemas/EntityResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-entities-id patch: tags: - Entidades summary: Atualizar entidade description: Nome, chave, campos especiais, paginação, filtros e modo da sincronização, e a lista de campos (casada por chave). Quando o mapeamento muda, os registros são relidos. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) da entidade. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/EntityUpdateRequest" responses: "200": description: Entidade atualizada. content: application/json: schema: $ref: "#/components/schemas/EntityResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: "Conflito: chave já usada no workspace, ou a entidade é lida por uma relação." content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-entities-id delete: tags: - Entidades summary: Remover entidade description: Remove (soft delete) a entidade e seus campos. Recusado (409) enquanto uma entidade de relação a lê. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) da entidade. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Entidade removida. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: "Conflito: chave já usada no workspace, ou a entidade é lida por uma relação." content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-entities-id /v1/entities/{id}/join: put: tags: - Entidades summary: Alterar relação description: Troca a relação de uma entidade join e os campos que ela traz, e relê seus registros. 422 quando a entidade não é uma relação. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) da entidade. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/EntityJoinRequest" responses: "200": description: Entidade atualizada. content: application/json: schema: $ref: "#/components/schemas/EntityResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: "Conflito: chave já usada no workspace, ou a entidade é lida por uma relação." content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-entities-id-join /v1/entities/{id}/records: get: tags: - Entidades summary: Consultar registros description: Os registros sincronizados da entidade, com filtro por campo, ordenação e paginação por `limit`/`offset` (a mesma consulta dos blocos do portal). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) da entidade. required: true name: id in: path - schema: type: integer minimum: 1 maximum: 200 description: Registros por chamada (padrão 50, máximo 200). example: 50 required: false name: limit in: query - schema: type: - integer - "null" minimum: 0 maximum: 10000 description: Quantos registros pular. example: 0 required: false name: offset in: query - schema: type: string description: Chaves de campo com direção opcional, separadas por vírgula (`campo:desc,outro`); `asc` por padrão. example: due_date:desc,name required: false name: sort in: query - schema: type: string description: 'Objeto JSON de condições por campo: `{"campo": valor}` ou `{"campo": {"gte": 10}}`. Operadores: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `contains`, `is_null`.' example: '{"status":"open","amount":{"gte":100}}' required: false name: filter in: query - schema: type: string format: uuid description: "ID de um usuário do portal: só os registros dele, como o portal mostra (em uma entidade `on_access`, sincroniza esse titular antes)." required: false name: preview_as in: query - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Registros da entidade. content: application/json: schema: $ref: "#/components/schemas/EntityRecordsQueryResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-entities-id-records delete: tags: - Entidades summary: Limpar registros description: Remove todos os registros sincronizados da entidade e zera o estado da sincronização, para a próxima ler a origem do zero. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) da entidade. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Registros removidos. content: application/json: schema: $ref: "#/components/schemas/EntityRecordsClearedResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-entities-id-records /v1/entities/{id}/records/{record_id}: get: tags: - Entidades summary: Consultar registro description: Um registro sincronizado — valores por campo e o registro como a origem o enviou — com a sua entidade. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) da entidade. required: true name: id in: path - schema: type: string format: uuid description: ID (UUID) do registro sincronizado — o `_record.id` de um registro listado. required: true name: record_id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: O registro e a entidade. content: application/json: schema: $ref: "#/components/schemas/EntityRecordResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-entities-id-records-record-id /v1/entities/{id}/aggregate: get: tags: - Entidades summary: Agregar registros description: Contagem, soma, média, mínimo ou máximo sobre os registros sincronizados, opcionalmente agrupados por um campo — o que os blocos de KPI e gráfico mostram. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) da entidade. required: true name: id in: path - schema: type: string enum: - count - sum - avg - min - max description: "Agregação: `count` (padrão), `sum`, `avg`, `min` ou `max`." required: false name: op in: query - schema: type: string description: Chave do campo agregado (obrigatória exceto em `count`; numérico em `sum`/`avg`). required: false name: field in: query - schema: type: string description: Chave do campo pelo qual agrupar. required: false name: group_by in: query - schema: type: string description: 'Objeto JSON de condições por campo: `{"campo": valor}` ou `{"campo": {"gte": 10}}`. Operadores: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `contains`, `is_null`.' example: '{"status":"open","amount":{"gte":100}}' required: false name: filter in: query - schema: type: string format: uuid description: "ID de um usuário do portal: só os registros dele, como o portal mostra (em uma entidade `on_access`, sincroniza esse titular antes)." required: false name: preview_as in: query - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Resultado da agregação. content: application/json: schema: $ref: "#/components/schemas/EntityAggregateResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-entities-id-aggregate /v1/entities/{id}/usage: get: tags: - Entidades summary: Uso da entidade description: As páginas do portal (rascunho e publicada) cujos blocos leem a entidade — o que quebra se ela for removida ou sua chave mudar. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) da entidade. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Páginas que usam a entidade. content: application/json: schema: $ref: "#/components/schemas/EntityUsageResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-entities-id-usage /v1/entities/{id}/logs: get: tags: - Entidades summary: Log da sincronização description: "As chamadas que a sincronização da entidade fez ao conector, das mais novas às mais antigas: o log de requisições do conector restrito à entidade." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) da entidade. required: true name: id in: path - schema: type: integer minimum: 1 description: "Página (começa em 1). Padrão: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Itens por página. Padrão: `20`. Máximo: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Método HTTP da chamada, como `GET`. required: false name: method in: query - schema: type: string enum: - "true" - "false" description: Só chamadas bem-sucedidas (`true`) ou com falha (`false`). required: false name: success in: query - schema: type: string description: Parte do endpoint chamado. required: false name: search in: query - schema: type: string format: date description: Primeiro dia (AAAA-MM-DD). example: 2026-01-01 required: false name: date_from in: query - schema: type: string format: date description: Último dia, inclusive (AAAA-MM-DD). example: 2026-01-31 required: false name: date_to in: query - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Chamadas da sincronização. content: application/json: schema: $ref: "#/components/schemas/EntitySyncLogListResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-entities-id-logs /v1/entities/{id}/logs/{log_id}: get: tags: - Entidades summary: Consultar chamada da sincronização description: Uma chamada da sincronização da entidade, inteira (segredos mascarados). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) da entidade. required: true name: id in: path - schema: type: string format: uuid description: ID (UUID) da chamada no log de requisições. required: true name: log_id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: A chamada. content: application/json: schema: $ref: "#/components/schemas/EntitySyncLogResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-entities-id-logs-log-id /v1/entities/{id}/sync: post: tags: - Entidades summary: Sincronizar entidade description: "Enfileira uma sincronização da entidade e responde 202 com o ID; o andamento fica em `GET /entities/{id}/sync`. Uma entidade `on_access` não tem sincronização geral (422): use `POST /entities/{id}/tenant_syncs`." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) da entidade. required: true name: id in: path - schema: type: string enum: - "true" - "1" description: "`true` (ou `1`) relê tudo e descarta o que a origem não tem mais; sem ele, a sincronização é incremental quando a origem permite." required: false name: full in: query - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "202": description: Sincronização enfileirada. content: application/json: schema: $ref: "#/components/schemas/EntitySyncQueuedResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-entities-id-sync get: tags: - Entidades summary: Estado da sincronização description: "Onde está a sincronização da entidade: status, último erro, últimas sincronizações, total de registros e estatísticas." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) da entidade. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Estado da sincronização. content: application/json: schema: $ref: "#/components/schemas/EntitySyncStateResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-entities-id-sync /v1/entities/{id}/tenant_syncs: get: tags: - Entidades summary: Sincronizações por titular description: "Em uma entidade `on_access`: onde está a sincronização de cada titular, dos acessados mais recentemente aos mais antigos." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) da entidade. required: true name: id in: path - schema: type: integer minimum: 1 description: "Página (começa em 1). Padrão: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Itens por página. Padrão: `20`. Máximo: `100`." example: 20 required: false name: per_page in: query - schema: type: string enum: - queued - running - completed - error description: Status da sincronização do titular. required: false name: status in: query - schema: type: string maxLength: 200 description: Parte do Tenant ID. required: false name: search in: query - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Sincronizações dos titulares. content: application/json: schema: $ref: "#/components/schemas/EntityTenantSyncListResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-entities-id-tenant-syncs post: tags: - Entidades summary: Sincronizar um titular description: Enfileira agora a sincronização de um titular de uma entidade `on_access`. 404 quando nenhum usuário do portal tem esse Tenant ID; 422 quando a entidade não é `on_access`. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) da entidade. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/EntityTenantSyncRequest" responses: "202": description: Sincronização enfileirada. content: application/json: schema: $ref: "#/components/schemas/EntityTenantSyncQueuedResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-entities-id-tenant-syncs /v1/portal_builder: get: tags: - Construtor do Portal summary: Consultar o construtor do portal description: "Retorna o portal do workspace como o construtor o vê: identidade do portal, rascunho (páginas na ordem do menu, cada uma com sua marca em relação à versão no ar, `revision` e `dirty`), número da versão no ar, versões publicadas, tema e SEO padrão. Leia a `revision` daqui antes de salvar o rascunho." security: - bearerAuth: [] responses: "200": description: O construtor do portal. content: application/json: schema: $ref: "#/components/schemas/PortalBuilderResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-portal-builder parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/portal_builder/draft: put: tags: - Construtor do Portal summary: Salvar o rascunho do portal description: "Substitui o rascunho inteiro — páginas na ordem do menu, estado do editor e, opcionalmente, tema e SEO padrão — protegido pela `revision` lida por último. Uma `revision` desatualizada responde 409 e não altera nada. Nada vai ao ar: para publicar, use `POST /portal_builder/publish`." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PortalBuilderDraftRequest" responses: "200": description: "Rascunho salvo: nova `revision`, se difere da versão no ar e a marca de cada página." content: application/json: schema: $ref: "#/components/schemas/PortalBuilderDraftSaveResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: "A `revision` enviada está desatualizada: o rascunho foi salvo por outra pessoa ou aba. Leia de novo e reenvie." content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-portal-builder-draft parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/portal_builder/publish: post: tags: - Construtor do Portal summary: Publicar o portal description: "Salva o rascunho como enviado (mesmo corpo do salvamento, mais uma `note` opcional) e o congela como a próxima versão, numa única transação: os visitantes do portal passam a vê-la na hora. Um campo de formulário cuja expressão regular pode travar a validação responde 422 `UNSAFE_FIELD_PATTERN`." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PortalBuilderPublishRequest" responses: "201": description: Versão publicada, com a nova `revision` do rascunho. content: application/json: schema: $ref: "#/components/schemas/PortalBuilderPublishResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: "A `revision` enviada está desatualizada: o rascunho foi salvo por outra pessoa ou aba. Leia de novo e reenvie." content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Uma expressão regular de campo de formulário pode travar a validação (`UNSAFE_FIELD_PATTERN`); `details` aponta página, bloco e campo. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-portal-builder-publish parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/portal_builder/versions/{number}: get: tags: - Construtor do Portal summary: Consultar uma versão publicada description: Retorna uma versão publicada do portal, pelo número, com as páginas que ela congelou. security: - bearerAuth: [] parameters: - schema: type: string description: Número da versão publicada (`1`, `2`…). example: "3" required: true name: number in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: A versão e suas páginas. content: application/json: schema: $ref: "#/components/schemas/PortalVersionDetailResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-portal-builder-versions-number /v1/portal_builder/versions/{number}/rollback: post: tags: - Construtor do Portal summary: Restaurar uma versão description: Coloca essa versão de volta no ar como o próximo número — os visitantes do portal a veem na hora. Retorna a nova versão e o construtor como ficou. security: - bearerAuth: [] parameters: - schema: type: string description: Número da versão publicada (`1`, `2`…). example: "3" required: true name: number in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "201": description: Nova versão no ar e o construtor atualizado. content: application/json: schema: $ref: "#/components/schemas/PortalBuilderRollbackResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Essa versão já está no ar (`ALREADY_LIVE`). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-portal-builder-versions-number-rollback /v1/portal_builder/secrets: post: tags: - Construtor do Portal summary: Criptografar um segredo de bloco description: "Criptografa um valor que um bloco guarda no JSON da página (um cabeçalho de webhook como `Authorization`). Retorna `secret:`, vinculado a este workspace e à origem de `url` (obrigatória), que só o servidor abre para enviar a requisição a essa origem. Nada é armazenado: salve o valor retornado no bloco junto com o rascunho." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PortalBuilderSecretRequest" responses: "200": description: O valor criptografado. content: application/json: schema: $ref: "#/components/schemas/PortalBuilderSecretResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: A `url` não tem uma origem http(s) fixa — por exemplo, uma `{{variável}}` no domínio (`ACTION_SECRET_URL_REQUIRED`). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-portal-builder-secrets parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/portal_builder/og_image: post: tags: - Construtor do Portal summary: Enviar uma imagem og:image description: Envia a og:image de uma página (ou do SEO padrão) — a imagem que as prévias de link mostram — e retorna a URL pública, para guardar em `seo.og_image_url` (ou `seo_defaults.og_image_url`) no próximo salvamento do rascunho. PNG, JPEG ou WebP, em base64; até 2 MB de imagem, mas o corpo inteiro da requisição tem limite de 2 MB (cerca de 1,5 MB de imagem depois de codificada). security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PortalBuilderOgImageRequest" responses: "201": description: Imagem enviada, com a URL pública. content: application/json: schema: $ref: "#/components/schemas/PortalBuilderOgImageResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "413": description: O corpo da requisição passou de 2 MB. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Tipo não aceito, base64 inválido, imagem acima do limite ou conteúdo que não corresponde ao `content_type`. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-portal-builder-og-image parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/portal_builder/form_submissions: post: tags: - Construtor do Portal summary: Testar um formulário do rascunho description: "Executa a ação de um bloco Formulário como a prévia do construtor: o e-mail configurado sai de verdade (ou o webhook escolhido dispara de verdade), marcado como `preview: true`. A configuração do formulário vem no corpo. O e-mail de teste vai só para o e-mail do operador do token (um token sem operador não testa a ação de e-mail). Limitado a 20 execuções por minuto por operador, 60 por minuto e 500 por dia por organização, compartilhando o limite com a prévia do painel." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PortalBuilderFormSubmissionRequest" responses: "200": description: "Envio registrado: destinatários, notificações ou entrega do webhook." content: application/json: schema: $ref: "#/components/schemas/PortalBuilderFormSubmissionResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Valores que não passam nas regras do formulário, expressão regular perigosa ou ação mal configurada; `field_errors` lista os campos. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-portal-builder-form-submissions parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/portal_builder/action_runs: post: tags: - Construtor do Portal summary: Testar um botão de ação do rascunho description: "Executa o webhook de um Botão de ação como a prévia do construtor: a requisição sai de verdade, marcada como `preview: true`, e a resposta traz o status HTTP devolvido pelo destino. Cabeçalhos podem levar valores `secret:` criados por `POST /portal_builder/secrets`, que só abrem para a origem para a qual foram criados. Limitado a 20 execuções por minuto por operador, 60 por minuto e 500 por dia por organização." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PortalBuilderActionRunRequest" responses: "200": description: Resultado da execução. content: application/json: schema: $ref: "#/components/schemas/PortalBuilderActionRunResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Requisição mal configurada (URL sem https, cabeçalho inválido, segredo de outro workspace…). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-portal-builder-action-runs parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/portal_settings: get: tags: - Configurações do Portal summary: Obter configurações do portal description: "Retorna a configuração do portal do workspace: marca, idioma da página, cores, endereço, opções de login e SSO, notificações e remetente, e configurações do site (cabeçalhos de segurança, SEO, rastreadores, chat e código próprio)." security: - bearerAuth: [] responses: "200": description: Configuração do portal do workspace, com os valores padrão aplicados. content: application/json: schema: $ref: "#/components/schemas/PortalSettingsResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-portal-settings parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier patch: tags: - Configurações do Portal summary: Atualizar configurações do portal description: "Atualiza a configuração do portal do workspace. Parcial: só os campos enviados mudam. Retorna a configuração completa." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PortalSettingsUpdateRequest" responses: "200": description: Configuração do portal do workspace, com os valores padrão aplicados. content: application/json: schema: $ref: "#/components/schemas/PortalSettingsResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Recusado por uma regra de negócio (endereço já em uso ou reservado, arquivo grande demais ou de tipo não aceito…). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-portal-settings parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/portal_settings/logo: post: tags: - Configurações do Portal summary: Enviar imagem do portal description: Envia o logo, o logo para fundos escuros ou o favicon do portal, em base64 no corpo JSON. Substitui a imagem anterior. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PortalLogoUploadRequest" responses: "201": description: Imagem salva; `url` é o endereço público. content: application/json: schema: $ref: "#/components/schemas/PortalLogoUploadResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Recusado por uma regra de negócio (endereço já em uso ou reservado, arquivo grande demais ou de tipo não aceito…). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-portal-settings-logo parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier delete: tags: - Configurações do Portal summary: Remover imagem do portal description: Remove o logo, o logo para fundos escuros ou o favicon; o portal volta ao padrão. security: - bearerAuth: [] parameters: - schema: type: string enum: - logo - logo_light - favicon description: "Qual imagem: `logo` (padrão), `logo_light` (logo para fundos escuros) ou `favicon`." required: false name: variant in: query - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Imagem removida. content: application/json: schema: $ref: "#/components/schemas/PortalLogoDeleteResponse" "400": description: Requisição inválida (parâmetro ausente ou fora do formato). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-portal-settings-logo /v1/portal_settings/domain: patch: tags: - Configurações do Portal summary: Definir endereço do portal description: Define o endereço do portal na plataforma, `https://{slug}.{domain}`, ou o remove quando os dois são `null`. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PortalDomainUpdateRequest" responses: "200": description: Endereço atualizado. content: application/json: schema: $ref: "#/components/schemas/PortalDomainResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Recusado por uma regra de negócio (endereço já em uso ou reservado, arquivo grande demais ou de tipo não aceito…). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-portal-settings-domain parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/portal_settings/domain/check_slug: get: tags: - Configurações do Portal summary: Verificar disponibilidade do endereço description: Informa se `slug.domain` está livre para o portal deste workspace (o endereço atual dele conta como livre). security: - bearerAuth: [] parameters: - schema: type: string description: "Subdomínio: 3 a 50 letras minúsculas, números e hífens (sem hífen nas pontas). `null` para remover." example: acme required: true name: slug in: query - schema: type: string description: Um dos domínios da plataforma (`available_domains`). `null` para remover. required: true name: domain in: query - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Resultado da verificação. content: application/json: schema: $ref: "#/components/schemas/PortalSlugCheckResponse" "400": description: Requisição inválida (parâmetro ausente ou fora do formato). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-portal-settings-domain-check-slug /v1/portal_settings/sender_identity: post: tags: - Configurações do Portal summary: Verificar remetente das notificações description: Pede ou confere a verificação do remetente no AWS SES. Se o endereço nunca foi enviado ao SES ou a verificação falhou, o SES envia a ele um link de confirmação; senão, consulta a situação atual. security: - bearerAuth: [] responses: "200": description: Situação da verificação. content: application/json: schema: $ref: "#/components/schemas/PortalSenderIdentityResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-portal-settings-sender-identity parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/portal_custom_domains: get: tags: - Domínios Próprios do Portal summary: Listar domínios próprios description: Lista os domínios próprios do portal do workspace (conjunto completo, sem paginação). Vazia onde domínios próprios não são suportados. security: - bearerAuth: [] responses: "200": description: Domínios próprios do portal. content: application/json: schema: $ref: "#/components/schemas/PortalCustomDomainListResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-portal-custom-domains parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier post: tags: - Domínios Próprios do Portal summary: Adicionar domínio próprio description: "Registra um domínio próprio como `pending_verification`, sem acionar a AWS, e retorna os registros DNS a publicar. Depois chame `POST /portal_custom_domains/{id}/verify`. O registro é só uma reivindicação: o domínio fica com o primeiro portal que publicar o TXT de verificação (as outras reivindicações não comprovadas são liberadas), e uma reivindicação não comprovada expira em 7 dias. Cada portal tem no máximo 10 domínios. Domínios da plataforma (`kobana.com.br`, `kobana.tech` e os domínios compartilhados de portal) não são aceitos. 403 onde domínios próprios não estão disponíveis." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PortalCustomDomainCreateRequest" responses: "201": description: O domínio próprio. content: application/json: schema: $ref: "#/components/schemas/PortalCustomDomainResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: Este domínio já está registrado (comprovado por outro portal, ou já reivindicado por este). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Domínio reservado da plataforma (`hostname_reserved`) ou limite de domínios do portal atingido (`domain_limit_reached`). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-portal-custom-domains parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/portal_custom_domains/{id}: delete: tags: - Domínios Próprios do Portal summary: Remover domínio próprio description: Remove o domínio próprio e desfaz o tenant da CloudFront e o certificado, quando provisionados. O portal deixa de responder nesse endereço. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID do domínio próprio. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Removido. content: application/json: schema: $ref: "#/components/schemas/PortalSettingsDeletedResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-portal-custom-domains-id /v1/portal_custom_domains/{id}/verify: post: tags: - Domínios Próprios do Portal summary: Verificar e provisionar domínio próprio description: Enquanto pendente, confere o DNS e provisiona o domínio na AWS (certificado e tenant da CloudFront); depois de provisionado, atualiza a situação. Retorna o domínio com o novo `status`. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID do domínio próprio. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: O domínio próprio. content: application/json: schema: $ref: "#/components/schemas/PortalCustomDomainResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-portal-custom-domains-id-verify /v1/portal_custom_domains/{id}/dns_status: get: tags: - Domínios Próprios do Portal summary: Consultar DNS do domínio próprio description: Consulta somente leitura dos CNAMEs exigidos, registro a registro, sem alterar nada na AWS. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID do domínio próprio. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Situação do DNS. content: application/json: schema: $ref: "#/components/schemas/PortalCustomDomainDnsStatusResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-portal-custom-domains-id-dns-status /v1/portal_oauth_providers: get: tags: - Provedores OIDC do Portal summary: Listar provedores OIDC description: Lista os provedores OpenID Connect com que os usuários entram no portal (conjunto completo, sem paginação). security: - bearerAuth: [] responses: "200": description: Provedores OIDC do portal. content: application/json: schema: $ref: "#/components/schemas/PortalOAuthProviderListResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-portal-oauth-providers parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier post: tags: - Provedores OIDC do Portal summary: Adicionar provedor OIDC description: Adiciona um provedor OpenID Connect ao login do portal. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PortalOAuthProviderCreateRequest" responses: "201": description: O provedor (sem o secret). content: application/json: schema: $ref: "#/components/schemas/PortalOAuthProviderResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-portal-oauth-providers parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/portal_oauth_providers/{id}: patch: tags: - Provedores OIDC do Portal summary: Atualizar provedor OIDC description: "Atualiza um provedor OpenID Connect. Parcial: só os campos enviados mudam." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID do provedor OIDC. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/PortalOAuthProviderUpdateRequest" responses: "200": description: O provedor (sem o secret). content: application/json: schema: $ref: "#/components/schemas/PortalOAuthProviderResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-portal-oauth-providers-id delete: tags: - Provedores OIDC do Portal summary: Remover provedor OIDC description: Remove o provedor; o botão some do login e ninguém mais entra por ele. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID do provedor OIDC. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Removido. content: application/json: schema: $ref: "#/components/schemas/PortalSettingsDeletedResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-portal-oauth-providers-id /v1/portal_oauth_providers/test: post: tags: - Provedores OIDC do Portal summary: Testar emissor OIDC description: "Busca o documento de descoberta do emissor e informa seus endpoints, para validar a URL antes de salvar. Uma falha na descoberta é um 200 com `ok: false`." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PortalOAuthProviderTestRequest" responses: "200": description: Resultado do teste. content: application/json: schema: $ref: "#/components/schemas/PortalOAuthProviderTestResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-portal-oauth-providers-test parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/webhooks: get: tags: - Webhooks summary: Listar endpoints de webhook description: Lista os endpoints de webhook do workspace, do mais recente ao mais antigo, com o total de entregas de cada um. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Página (começa em 1). Padrão: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Itens por página. Padrão: `20`. Máximo: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Campo de ordenação. Padrão depende do recurso. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Direção da ordenação. Padrão: `desc`." required: false name: sort_order in: query - schema: type: string enum: - active - inactive description: "`active` ou `inactive`." required: false name: status in: query - schema: type: string description: Trecho da URL ou da descrição, sem diferenciar maiúsculas. required: false name: search in: query - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Página de endpoints de webhook. content: application/json: schema: $ref: "#/components/schemas/WebhookListResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-webhooks post: tags: - Webhooks summary: Criar endpoint de webhook description: Cria um endpoint ativo no workspace. A resposta traz o `secret` de assinatura — ele só aparece aqui (e na rotação). security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/WebhookCreateRequest" responses: "201": description: Endpoint criado, com o segredo de assinatura. content: application/json: schema: $ref: "#/components/schemas/WebhookWithSecretResponse" "400": description: "Requisição inválida: corpo malformado, campo obrigatório ausente ou filtro com valor inválido." content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-webhooks parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/webhooks/{id}: get: tags: - Webhooks summary: Consultar endpoint de webhook description: Retorna um endpoint de webhook do workspace. As entregas ficam em `GET /webhooks/{id}/deliveries`. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) do endpoint de webhook. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: O endpoint de webhook. content: application/json: schema: $ref: "#/components/schemas/WebhookResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-webhooks-id patch: tags: - Webhooks summary: Atualizar endpoint de webhook description: Altera URL, descrição, eventos assinados, `active` ou a autenticação. Campos ausentes ficam como estão. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) do endpoint de webhook. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/WebhookUpdateRequest" responses: "200": description: Endpoint atualizado. content: application/json: schema: $ref: "#/components/schemas/WebhookResponse" "400": description: "Requisição inválida: corpo malformado, campo obrigatório ausente ou filtro com valor inválido." content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-webhooks-id delete: tags: - Webhooks summary: Excluir endpoint de webhook description: Exclui o endpoint definitivamente, junto com o log de entregas. Os eventos deixam de ser enviados na hora. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) do endpoint de webhook. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Endpoint excluído. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-webhooks-id /v1/webhooks/{id}/test: post: tags: - Webhooks summary: Enviar webhook de teste description: "Envia agora um evento `test.webhook` assinado para a URL do endpoint e o registra no log de entregas. Responde 200 com `success: false` quando o endpoint responde fora de 2xx ou não é alcançado, e 422 quando a URL aponta para um endereço bloqueado (rede privada)." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) do endpoint de webhook. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Resultado da tentativa. content: application/json: schema: $ref: "#/components/schemas/WebhookTestResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-webhooks-id-test /v1/webhooks/{id}/rotate_secret: post: tags: - Webhooks summary: Rotacionar segredo do webhook description: Gera um novo segredo de assinatura. O anterior deixa de valer na hora; o novo `secret` só aparece nesta resposta. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) do endpoint de webhook. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Endpoint com o novo segredo. content: application/json: schema: $ref: "#/components/schemas/WebhookWithSecretResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-webhooks-id-rotate-secret /v1/webhooks/{id}/deliveries: get: tags: - Webhooks summary: Listar entregas de um webhook description: Log de entregas de um endpoint, da mais recente à mais antiga. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) do endpoint de webhook. required: true name: id in: path - schema: type: integer minimum: 1 description: "Página (começa em 1). Padrão: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Itens por página. Padrão: `20`. Máximo: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Campo de ordenação. Padrão depende do recurso. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Direção da ordenação. Padrão: `desc`." required: false name: sort_order in: query - schema: type: string enum: - pending - delivered - failed description: "`pending`, `delivered` ou `failed`." required: false name: status in: query - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Página de entregas. content: application/json: schema: $ref: "#/components/schemas/WebhookDeliveryListResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-webhooks-id-deliveries /v1/webhooks/{id}/deliveries/{delivery_id}/retry: post: tags: - Webhooks summary: Reenviar entrega de webhook description: "Coloca a entrega de volta em `pending` e a enfileira para novo envio. O envio é assíncrono: acompanhe o resultado no log de entregas." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) do endpoint de webhook. required: true name: id in: path - schema: type: string format: uuid description: ID (UUID) da entrega, obtido no log de entregas. required: true name: delivery_id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "202": description: Entrega enfileirada para reenvio. content: application/json: schema: $ref: "#/components/schemas/WebhookDeliveryRetryResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-webhooks-id-deliveries-delivery-id-retry /v1/webhook_deliveries: get: tags: - Webhooks summary: Listar entregas de webhook description: Entregas de todos os endpoints do workspace, da mais recente à mais antiga, com o tipo do evento e o resumo do endpoint. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Página (começa em 1). Padrão: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Itens por página. Padrão: `20`. Máximo: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Campo de ordenação. Padrão depende do recurso. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Direção da ordenação. Padrão: `desc`." required: false name: sort_order in: query - schema: type: string enum: - pending - delivered - failed description: "`pending`, `delivered` ou `failed`." required: false name: status in: query - schema: type: string format: uuid description: Somente entregas deste endpoint de webhook. required: false name: webhook_id in: query - schema: type: string description: Limite inferior de `created_at` (data ou data-hora ISO 8601). required: false name: date_from in: query - schema: type: string description: Limite superior de `created_at` (data ou data-hora ISO 8601). Uma data sem hora cobre o dia inteiro (UTC). required: false name: date_to in: query - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Página de entregas. content: application/json: schema: $ref: "#/components/schemas/WebhookDeliveryListResponse" "400": description: "Requisição inválida: corpo malformado, campo obrigatório ausente ou filtro com valor inválido." content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-webhook-deliveries /v1/webhook_deliveries/{id}: get: tags: - Webhooks summary: Consultar entrega de webhook description: "Retorna uma entrega: requisição (redigida), resposta, tentativas e o endpoint de destino." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) da entrega. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: A entrega. content: application/json: schema: $ref: "#/components/schemas/WebhookDeliveryResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-webhook-deliveries-id /v1/events: get: tags: - Eventos summary: Listar eventos description: "Log de eventos do workspace e da organização, do mais recente ao mais antigo. Eventos são evidência: não podem ser alterados nem excluídos." security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Página (começa em 1). Padrão: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Itens por página. Padrão: `20`. Máximo: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Campo de ordenação. Padrão depende do recurso. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Direção da ordenação. Padrão: `desc`." required: false name: sort_order in: query - schema: type: string description: "Tipo exato do evento (ex.: `api_key.rotated`)." required: false name: type in: query - schema: type: string description: "Tipo exato do recurso (ex.: `api_key`)." required: false name: resource_type in: query - schema: type: string format: uuid description: Somente eventos deste registro. required: false name: resource_id in: query - schema: type: string description: Limite inferior de `created_at` (data ou data-hora ISO 8601). required: false name: date_from in: query - schema: type: string description: Limite superior de `created_at` (data ou data-hora ISO 8601). Uma data sem hora cobre o dia inteiro (UTC). required: false name: date_to in: query - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Página de eventos. content: application/json: schema: $ref: "#/components/schemas/EventListResponse" "400": description: "Requisição inválida: corpo malformado, campo obrigatório ausente ou filtro com valor inválido." content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-events /v1/events/{id}: get: tags: - Eventos summary: Consultar evento description: Retorna um evento com o payload completo. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) do evento. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: O evento. content: application/json: schema: $ref: "#/components/schemas/EventResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-events-id /v1/audit_logs: get: tags: - Auditoria summary: Listar registros de auditoria description: Trilha de auditoria do workspace e da organização, do mais recente ao mais antigo. A trilha não pode ser alterada. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Página (começa em 1). Padrão: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Itens por página. Padrão: `20`. Máximo: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Campo de ordenação. Padrão depende do recurso. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Direção da ordenação. Padrão: `desc`." required: false name: sort_order in: query - schema: type: string description: Identificador exato do usuário. required: false name: user_id in: query - schema: type: string description: "Ação exata (ex.: `webhook.created`)." required: false name: action in: query - schema: type: string description: "Tipo exato do recurso (ex.: `webhook`)." required: false name: resource_type in: query - schema: type: string description: ID exato do recurso. required: false name: resource_id in: query - schema: type: string description: Trecho da ação, do tipo de recurso, do ID ou do e-mail do usuário, sem diferenciar maiúsculas. required: false name: search in: query - schema: type: string description: Limite inferior de `created_at` (data ou data-hora ISO 8601). required: false name: date_from in: query - schema: type: string description: Limite superior de `created_at` (data ou data-hora ISO 8601). Uma data sem hora cobre o dia inteiro (UTC). required: false name: date_to in: query - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Página de registros de auditoria. content: application/json: schema: $ref: "#/components/schemas/AuditLogListResponse" "400": description: "Requisição inválida: corpo malformado, campo obrigatório ausente ou filtro com valor inválido." content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-audit-logs /v1/audit_logs/summary: get: tags: - Auditoria summary: Resumo da atividade auditada description: "Atividade das últimas `hours` horas: total de registros, as 10 ações mais frequentes e os 20 registros mais recentes. Exige a permissão de exportar auditoria." security: - bearerAuth: [] parameters: - schema: type: number minimum: 1 maximum: 8760 description: Tamanho da janela em horas, de 1 a 8760. Padrão 24. example: 24 required: false name: hours in: query - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Resumo da atividade. content: application/json: schema: $ref: "#/components/schemas/AuditLogSummaryResponse" "400": description: "Requisição inválida: corpo malformado, campo obrigatório ausente ou filtro com valor inválido." content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-audit-logs-summary /v1/audit_logs/{id}: get: tags: - Auditoria summary: Consultar registro de auditoria description: Retorna um registro de auditoria com valores anteriores e novos. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) do registro de auditoria. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: O registro de auditoria. content: application/json: schema: $ref: "#/components/schemas/AuditLogResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-audit-logs-id /v1/email_templates: get: tags: - Modelos de E-mail summary: Listar modelos de e-mail description: Lista os modelos de e-mail da própria organização, ordenados por tipo e nome. Retorna o conjunto inteiro, sem paginação. security: - bearerAuth: [] parameters: - schema: type: string enum: - api_key_expiring - account_suspended - account_activated - portal_invitation - portal_signup_verification - magic_link_portal - magic_link_dashboard - email_verification - password_reset - welcome - email_change_verification - password_verification - account_invitation - organization_welcome - dashboard_user_welcome description: Somente modelos deste tipo de notificação. required: false name: type in: query - schema: type: string enum: - "true" - "false" description: "`true` para os modelos ativos, `false` para os rascunhos." required: false name: is_active in: query - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Modelos da organização. content: application/json: schema: $ref: "#/components/schemas/EmailTemplateListResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-email-templates post: tags: - Modelos de E-mail summary: Criar modelo de e-mail description: Cria um modelo para um tipo de notificação. Fica como rascunho, a menos que `is_active` seja `true` — nesse caso o modelo ativo anterior do tipo vira rascunho. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/EmailTemplateCreateRequest" responses: "201": description: Modelo criado. content: application/json: schema: $ref: "#/components/schemas/EmailTemplateResponse" "400": description: Requisição inválida (campo obrigatório ausente, tipo ou variáveis inválidos). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-email-templates parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/email_templates/init_defaults: post: tags: - Modelos de E-mail summary: Restaurar modelos padrão description: Cria ou restaura o modelo de cada tipo de notificação com o conteúdo padrão e o ativa. Sobrescreve o conteúdo dos modelos existentes da organização. security: - bearerAuth: [] responses: "200": description: Uma linha por tipo de notificação. content: application/json: schema: $ref: "#/components/schemas/EmailTemplateDefaultsResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-email-templates-init-defaults parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/email_templates/{id}: get: tags: - Modelos de E-mail summary: Consultar modelo de e-mail description: Retorna um modelo da organização ou um modelo padrão da plataforma. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) do modelo. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: O modelo. content: application/json: schema: $ref: "#/components/schemas/EmailTemplateResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-email-templates-id patch: tags: - Modelos de E-mail summary: Atualizar modelo de e-mail description: Atualiza um modelo da organização. Só os campos enviados mudam. Modelos padrão da plataforma não podem ser alterados (404). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) do modelo. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/EmailTemplateUpdateRequest" responses: "200": description: Modelo atualizado. content: application/json: schema: $ref: "#/components/schemas/EmailTemplateResponse" "400": description: Requisição inválida (campo obrigatório ausente, tipo ou variáveis inválidos). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: O `public_id` informado já está em uso. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-email-templates-id delete: tags: - Modelos de E-mail summary: Excluir modelo de e-mail description: "Exclui definitivamente um modelo inativo da organização. O modelo ativo de um tipo não pode ser excluído (422): ative outro antes." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) do modelo. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Modelo excluído. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-email-templates-id /v1/email_templates/{id}/duplicate: post: tags: - Modelos de E-mail summary: Duplicar modelo de e-mail description: Copia um modelo como rascunho (inativo). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) do modelo. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/EmailTemplateDuplicateRequest" responses: "201": description: A cópia criada. content: application/json: schema: $ref: "#/components/schemas/EmailTemplateResponse" "400": description: Requisição inválida (campo obrigatório ausente, tipo ou variáveis inválidos). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-email-templates-id-duplicate /v1/email_templates/{id}/preview: get: tags: - Modelos de E-mail summary: Pré-visualizar modelo de e-mail description: Renderiza o modelo com dados de exemplo, dentro do layout da organização. Nada é enviado. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) do modelo. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: O e-mail renderizado. content: application/json: schema: $ref: "#/components/schemas/EmailTemplateRenderResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-email-templates-id-preview post: tags: - Modelos de E-mail summary: Renderizar modelo com variáveis description: Renderiza o modelo com as `variables` enviadas, sem layout. Nada é enviado. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) do modelo. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/EmailTemplateRenderRequest" responses: "200": description: O e-mail renderizado. content: application/json: schema: $ref: "#/components/schemas/EmailTemplateRenderResponse" "400": description: Requisição inválida (campo obrigatório ausente, tipo ou variáveis inválidos). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-email-templates-id-preview /v1/email_layouts: get: tags: - Layouts de E-mail summary: Listar layouts de e-mail description: Lista os layouts de e-mail da organização, o padrão primeiro. Retorna o conjunto inteiro, sem paginação. security: - bearerAuth: [] responses: "200": description: Layouts da organização. content: application/json: schema: $ref: "#/components/schemas/EmailLayoutListResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-email-layouts parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier post: tags: - Layouts de E-mail summary: Criar layout de e-mail description: Cria um layout. O HTML precisa conter o marcador `{{content}}`. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/EmailLayoutCreateRequest" responses: "201": description: Layout criado. content: application/json: schema: $ref: "#/components/schemas/EmailLayoutResponse" "400": description: Requisição inválida (campo obrigatório ausente, tipo ou variáveis inválidos). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-email-layouts parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/email_layouts/init_defaults: post: tags: - Layouts de E-mail summary: Criar layout padrão description: "Garante que a organização tenha um layout padrão: retorna o atual ou cria o embutido. Nunca sobrescreve um layout." security: - bearerAuth: [] responses: "200": description: O layout padrão. content: application/json: schema: $ref: "#/components/schemas/EmailLayoutResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-email-layouts-init-defaults parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/email_layouts/{id}: get: tags: - Layouts de E-mail summary: Consultar layout de e-mail description: Retorna um layout da organização. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) do layout. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: O layout. content: application/json: schema: $ref: "#/components/schemas/EmailLayoutResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-email-layouts-id patch: tags: - Layouts de E-mail summary: Atualizar layout de e-mail description: Atualiza nome, HTML (que deve manter `{{content}}`), padrão ou ativo. Só os campos enviados mudam. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) do layout. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/EmailLayoutUpdateRequest" responses: "200": description: Layout atualizado. content: application/json: schema: $ref: "#/components/schemas/EmailLayoutResponse" "400": description: Requisição inválida (campo obrigatório ausente, tipo ou variáveis inválidos). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-email-layouts-id delete: tags: - Layouts de E-mail summary: Excluir layout de e-mail description: Exclui definitivamente um layout. Os e-mails passam a usar o layout padrão (ou o embutido). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) do layout. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Layout excluído. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-email-layouts-id /v1/notifications: get: tags: - Notificações summary: Listar notificações description: Lista as notificações do workspace e as da organização inteira, das mais novas para as mais antigas. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Página (começa em 1). Padrão: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Itens por página. Padrão: `20`. Máximo: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Campo de ordenação. Padrão depende do recurso. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Direção da ordenação. Padrão: `desc`." required: false name: sort_order in: query - schema: type: string enum: - api_key_expiring - account_suspended - account_activated - portal_invitation - portal_signup_verification - magic_link_portal - magic_link_dashboard - email_verification - password_reset - welcome - email_change_verification - password_verification - account_invitation - organization_welcome - dashboard_user_welcome description: Somente este tipo de notificação. required: false name: type in: query - schema: type: string enum: - email - in_app - webhook description: Somente este canal. required: false name: channel in: query - schema: type: string enum: - pending - sent - delivered - failed - read - skipped description: Somente este status. required: false name: status in: query - schema: type: string description: Data de criação inicial do intervalo (YYYY-MM-DD). required: false name: created_after in: query - schema: type: string description: Data de criação final do intervalo (YYYY-MM-DD). required: false name: created_before in: query - schema: type: string description: Trecho do destinatário ou do assunto, sem diferenciar maiúsculas. required: false name: search in: query - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Página de notificações. content: application/json: schema: $ref: "#/components/schemas/NotificationListResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-notifications post: tags: - Notificações summary: Criar notificação description: Renderiza o modelo ativo do tipo com as variáveis, grava a notificação e a envia na hora — a resposta traz o resultado (`sent`, ou `failed` com `failure_reason`). Com um `scheduled_for` no futuro, ela fica `pending` até a hora marcada. Cada criação conta no limite de envios manuais por destinatário (429). security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/NotificationCreateRequest" responses: "201": description: Notificação criada. content: application/json: schema: $ref: "#/components/schemas/NotificationResponse" "400": description: Requisição inválida (campo obrigatório ausente, tipo ou variáveis inválidos). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-notifications parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/notifications/stats: get: tags: - Notificações summary: Estatísticas de notificações description: Contagens por status, tipo e canal das notificações criadas nos últimos `days` dias, com as taxas de entrega e de leitura. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 maximum: 365 description: Janela em dias, de 1 a 365. Padrão 30. example: 30 required: false name: days in: query - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: As estatísticas. content: application/json: schema: $ref: "#/components/schemas/NotificationStatsResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-notifications-stats /v1/notifications/{id}/send: post: tags: - Notificações summary: Enviar notificação description: "Envia agora uma notificação gravada: o primeiro envio de uma `pending` (agendada) ou `skipped`, ou o reenvio de uma `sent`, `delivered`, `read` ou `failed`. Cada chamada envia o e-mail de novo e conta no limite de envios manuais por destinatário (429)." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) da notificação. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: A notificação atualizada. content: application/json: schema: $ref: "#/components/schemas/NotificationSendResponse" "400": description: Requisição inválida (campo obrigatório ausente, tipo ou variáveis inválidos). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "502": description: O provedor de e-mail recusou o envio; o motivo vem na mensagem. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-notifications-id-send /v1/api_keys: get: tags: - Chaves de API summary: Listar chaves de API description: "Lista as chaves de API (`kb_…`) da organização, sem o segredo. Essas chaves não autenticam mais a API v1 nem o MCP — ambos usam tokens de acesso emitidos pelo servidor de autorização da Kobana; os registros continuam como inventário de chaves da organização (ciclo de vida, avisos de expiração e webhooks `api_key.*`). Recurso da organização: não usa `X-Workspace-Id`." security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Página (começa em 1). Padrão: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Itens por página. Padrão: `20`. Máximo: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Campo de ordenação. Padrão depende do recurso. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Direção da ordenação. Padrão: `desc`." required: false name: sort_order in: query - schema: type: string enum: - active - disabled - revoked description: "Filtra pelo status: `active`, `disabled` ou `revoked`." required: false name: status in: query - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Página de chaves de API. content: application/json: schema: $ref: "#/components/schemas/ApiKeyListResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-api-keys post: tags: - Chaves de API summary: Criar chave de API description: Cria uma chave ativa, válida por um ano salvo `expires_at`. O segredo (`key`) volta UMA única vez nesta resposta — só o hash é guardado. Exige uma pessoa que alcance todos os workspaces (dona da organização ou com acesso a cada um), como no painel. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ApiKeyCreateRequest" responses: "201": description: Chave criada, com o segredo em `key` (exibido só agora). content: application/json: schema: $ref: "#/components/schemas/ApiKeyCreatedResponse" "400": description: Corpo ausente, JSON inválido ou campos incompatíveis. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-api-keys parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/api_keys/{id}: get: tags: - Chaves de API summary: Consultar chave de API description: Retorna uma chave da organização — metadados e carimbos do ciclo de vida, nunca o segredo. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) da chave de API. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: A chave de API. content: application/json: schema: $ref: "#/components/schemas/ApiKeyResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-api-keys-id patch: tags: - Chaves de API summary: Atualizar chave de API description: Edita nome, descrição, origem, e-mails de aviso e validade, e/ou ativa ⇄ desativa a chave com `enabled`. Chave revogada é definitiva (409). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) da chave de API. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/ApiKeyUpdateRequest" responses: "200": description: A chave de API. content: application/json: schema: $ref: "#/components/schemas/ApiKeyResponse" "400": description: Corpo ausente, JSON inválido ou campos incompatíveis. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: O estado atual do recurso não permite esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-api-keys-id delete: tags: - Chaves de API summary: Remover chave revogada description: Tira da lista uma chave JÁ REVOGADA (exclusão lógica; o histórico fica). Uma chave ativa ou desativada precisa ser revogada antes (409). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) da chave de API. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Removido. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: O estado atual do recurso não permite esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-api-keys-id /v1/api_keys/{id}/revoke: post: tags: - Chaves de API summary: Revogar chave de API description: Revoga a chave em definitivo — não pode ser reativada. 409 se já estiver revogada. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) da chave de API. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: A chave de API. content: application/json: schema: $ref: "#/components/schemas/ApiKeyResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: O estado atual do recurso não permite esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-api-keys-id-revoke /v1/api_keys/{id}/rotate: post: tags: - Chaves de API summary: Rotacionar chave de API description: Emite uma chave sucessora (mesmo nome e configurações) e mantém a anterior funcionando por `grace_days` dias (padrão 7, máximo 30). Só uma chave ativa pode ser rotacionada (409). O segredo novo volta UMA única vez. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) da chave de API. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/ApiKeyRotateRequest" responses: "200": description: A chave sucessora com o segredo em `key`, e `previous_key` com o prazo de carência da anterior. content: application/json: schema: $ref: "#/components/schemas/ApiKeyRotatedResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: O estado atual do recurso não permite esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-api-keys-id-rotate /v1/exports: get: tags: - Exportações summary: Listar exportações description: Lista os pedidos de exportação do workspace. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Página (começa em 1). Padrão: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Itens por página. Padrão: `20`. Máximo: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Campo de ordenação. Padrão depende do recurso. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Direção da ordenação. Padrão: `desc`." required: false name: sort_order in: query - schema: type: string description: "Recurso exportado, ex.: `portal_users`." required: false name: resource_type in: query - schema: type: string enum: - pending - processing - completed - failed description: Filtra pelo status da exportação. required: false name: status in: query - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Página de exportações. content: application/json: schema: $ref: "#/components/schemas/ExportListResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-exports post: tags: - Exportações summary: Solicitar exportação description: "Agenda a exportação dos usuários do portal do workspace em CSV, XLSX ou JSON. Assíncrono: responde 202 com a exportação `pending`; consulte `GET /exports/{id}` até `completed` e baixe em `/download`. O arquivo expira em 7 dias." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ExportCreateRequest" responses: "202": description: Exportação agendada. content: application/json: schema: $ref: "#/components/schemas/ExportResponse" "400": description: Corpo ausente, JSON inválido ou campos incompatíveis. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-exports parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/exports/{id}: get: tags: - Exportações summary: Consultar exportação description: Status e metadados de um pedido de exportação. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) da exportação. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: A exportação. content: application/json: schema: $ref: "#/components/schemas/ExportResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-exports-id /v1/exports/{id}/download: get: tags: - Exportações summary: Baixar arquivo da exportação description: Devolve o arquivo de uma exportação concluída (o painel redireciona para uma URL assinada; a API entrega os bytes). 404 enquanto não estiver pronta. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) da exportação. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: O arquivo, como anexo. content: text/csv: schema: type: string format: binary application/vnd.openxmlformats-officedocument.spreadsheetml.sheet: schema: type: string format: binary application/json: schema: type: string format: binary "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-exports-id-download /v1/imports: get: tags: - Importações summary: Listar importações description: Lista os pedidos de importação do workspace, com contadores de sucesso e erro. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Página (começa em 1). Padrão: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Itens por página. Padrão: `20`. Máximo: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Campo de ordenação. Padrão depende do recurso. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Direção da ordenação. Padrão: `desc`." required: false name: sort_order in: query - schema: type: string description: "Recurso importado, ex.: `portal_users`." required: false name: resource_type in: query - schema: type: string enum: - pending - processing - completed - completed_with_errors - failed description: Filtra pelo status da importação. required: false name: status in: query - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Página de importações. content: application/json: schema: $ref: "#/components/schemas/ImportListResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-imports post: tags: - Importações summary: Importar CSV description: 'Envia um CSV em base64 e agenda a importação de usuários do portal no workspace. O painel faz upload prévio do arquivo; a API o recebe no corpo (limite de 2 MB por requisição). Segue a configuração da organização "permitir criar usuários do portal" (403 quando desligada). Assíncrono: 202; consulte `GET /imports/{id}`.' security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ImportCreateRequest" responses: "202": description: Importação agendada. content: application/json: schema: $ref: "#/components/schemas/ImportResponse" "400": description: Corpo ausente, JSON inválido ou campos incompatíveis. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-imports parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/imports/{id}: get: tags: - Importações summary: Consultar importação description: Status, contadores e erros por linha de uma importação. Uma importação ainda `pending` 2 minutos depois do pedido aparece como `failed` (fila parada), sem que a consulta altere o registro. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) da importação. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: A importação. content: application/json: schema: $ref: "#/components/schemas/ImportResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-imports-id /v1/backups: get: tags: - Backups summary: Listar backups description: Lista backups e restaurações da organização (só metadados) e informa se um novo backup pode ser pedido agora (`backup_allowed`, `next_backup_at` — um a cada 12 horas em produção). Recurso da organização. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Página (começa em 1). Padrão: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Itens por página. Padrão: `20`. Máximo: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Campo de ordenação. Padrão depende do recurso. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Direção da ordenação. Padrão: `desc`." required: false name: sort_order in: query - schema: type: string enum: - backup - restore description: "`backup` ou `restore`." required: false name: type in: query - schema: type: string enum: - pending - processing - completed - failed - canceled description: Filtra pelo status. required: false name: status in: query - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Página de backups. content: application/json: schema: $ref: "#/components/schemas/BackupListResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-backups post: tags: - Backups summary: Solicitar backup description: "Agenda um backup completo (ZIP) da organização, com todos os workspaces. Assíncrono: 202; consulte `GET /backups/{id}`." security: - bearerAuth: [] responses: "202": description: Backup agendado. content: application/json: schema: $ref: "#/components/schemas/BackupResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Ainda dentro do intervalo de 12 horas entre backups (`BACKUP_COOLDOWN`, com `next_backup_at`). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-backups parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/backups/restore: post: tags: - Backups summary: Restaurar backup description: "DESTRUTIVO: restaura um backup no workspace da chamada (`X-Workspace-Id`), regravando usuários do portal casados por e-mail/ID público. Informe `backup_id` (um backup concluído desta organização — o arquivo é copiado) OU `file_name` (`.zip`) + `content_base64` (limitado aos 2 MB da requisição). Exige `settings.update` e acesso a todos os workspaces. Assíncrono: 202; acompanhe em `GET /backups/{id}` e cancele com `/cancel`." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/BackupRestoreRequest" responses: "202": description: Restauração agendada (registro do tipo `restore`). content: application/json: schema: $ref: "#/components/schemas/BackupResponse" "400": description: Corpo ausente, JSON inválido ou campos incompatíveis. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-backups-restore parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/backups/{id}: get: tags: - Backups summary: Consultar backup description: Status e progresso de um backup ou restauração. Uma restauração em andamento cujo job sumiu da fila é marcada como `failed`. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) do backup ou restauração. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: O backup. content: application/json: schema: $ref: "#/components/schemas/BackupResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-backups-id delete: tags: - Backups summary: Excluir backup description: Exclui o registro e o arquivo do armazenamento. Definitivo. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) do backup ou restauração. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Removido. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-backups-id /v1/backups/{id}/cancel: post: tags: - Backups summary: Cancelar restauração description: Interrompe uma restauração pendente ou em andamento. O que já foi restaurado permanece. 422 para um backup ou uma restauração já encerrada. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) do backup ou restauração. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: O backup. content: application/json: schema: $ref: "#/components/schemas/BackupResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-backups-id-cancel /v1/backups/{id}/download: get: tags: - Backups summary: Baixar backup description: Devolve o ZIP do backup. Exige `backups.export` e, para token de uma pessoa, ser dona da organização ou ter acesso a todos os workspaces — o backup contém todos eles. Fica registrado na auditoria. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) do backup ou restauração. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: O arquivo ZIP. content: application/zip: schema: type: string format: binary "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-backups-id-download /v1/data_purges: get: tags: - Limpeza de Dados summary: Contar dados apagáveis description: Quantos registros cada recurso apagável (`portal_users`, `people`, `usage_history`) tem somando todos os workspaces. Exige `data.purge` (por padrão só donos da organização) e acesso a todos os workspaces. security: - bearerAuth: [] responses: "200": description: As contagens. content: application/json: schema: $ref: "#/components/schemas/DataPurgeCountsResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-data-purges parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier post: tags: - Limpeza de Dados summary: Apagar dados da organização description: "IRREVERSÍVEL: apaga em definitivo os recursos escolhidos em TODOS os workspaces da organização. No painel, a operação é confirmada com um código enviado por e-mail. Por isso, um token que identifica uma pessoa (token pessoal, OAuth ou chamada pelo MCP) recebe 403: a pessoa faz a limpeza pelo painel. Só tokens de máquina podem limpar pela API, e só quando o token traz o escopo dedicado `dashboards/data_purges:write` — concedido explicitamente: nenhum outro escopo o implica (nem `write`, `all`, `dashboards/all` ou `dashboards/admin:write`); sem ele, 403 `insufficient_scope`. A confirmação deles é `confirm`, que precisa repetir o ID da organização (de `GET /organization`) — uma chamada repetida ou endereçada à organização errada não passa por engano. Exige `data.purge` (por padrão só donos da organização) e acesso a todos os workspaces. Assíncrono: 202 com `job_id`." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/DataPurgeRequest" responses: "202": description: Limpeza agendada; acompanhe em `GET /data_purges/{id}`. content: application/json: schema: $ref: "#/components/schemas/DataPurgeQueuedResponse" "400": description: Corpo ausente, JSON inválido ou campos incompatíveis. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: "`confirm` não corresponde ao ID da organização — nada foi apagado." content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-data-purges parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/data_purges/{id}: get: tags: - Limpeza de Dados summary: Acompanhar limpeza description: "Progresso e resultado de um job de limpeza. Job de outra organização: 404." security: - bearerAuth: [] parameters: - schema: type: string description: O `job_id` devolvido por `POST /data_purges`. required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: O job. content: application/json: schema: $ref: "#/components/schemas/DataPurgeJobResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-data-purges-id /v1/maintenance/uppercase_names: post: tags: - Manutenção summary: Colocar nomes em maiúsculas description: Converte para maiúsculas o nome de todo contato vinculado a um usuário do portal do workspace. Não é reversível (a grafia anterior não é guardada). security: - bearerAuth: [] responses: "200": description: Quantos nomes mudaram. content: application/json: schema: $ref: "#/components/schemas/MaintenanceUppercaseNamesResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-maintenance-uppercase-names parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/settings: get: tags: - Configurações summary: Consultar configurações da organização description: Nome, e-mail de suporte, fuso horário e as opções de cadastros da organização. Recurso da organização. security: - bearerAuth: [] responses: "200": description: As configurações. content: application/json: schema: $ref: "#/components/schemas/OrganizationSettingsResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-settings parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier put: tags: - Configurações summary: Atualizar configurações da organização description: "Altera parcialmente as configurações: envie só o que muda. Campos desconhecidos são recusados (400)." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/OrganizationSettingsUpdateRequest" responses: "200": description: As configurações. content: application/json: schema: $ref: "#/components/schemas/OrganizationSettingsResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-settings parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/usage: get: tags: - Consumo summary: Consultar consumo da plataforma description: "Para cada métrica (membros, clientes, usuários do portal, integrações…), a série diária no período, o valor mais recente e o pico. Padrão: mês corrente; no máximo 12 meses para trás. Recurso da organização." security: - bearerAuth: [] parameters: - schema: type: string format: date description: "Primeiro dia (AAAA-MM-DD). Padrão: dia 1 do mês corrente." example: 2026-01-15 required: false name: start_date in: query - schema: type: string format: date description: "Último dia (AAAA-MM-DD). Padrão: hoje." example: 2026-01-15 required: false name: end_date in: query - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: O consumo. content: application/json: schema: $ref: "#/components/schemas/SystemUsageResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-usage /v1/ai_usage: get: tags: - Uso de IA summary: Consultar uso de IA description: "Consumo de IA, só preço (custo e margem nunca saem): totais, detalhamento diário e últimos turnos do workspace da chamada, mais o acumulado do mês, franquias, limites, saldo de crédito e se o próximo turno é permitido — esses da organização inteira, pois o limite e o crédito são compartilhados. Período padrão: mês corrente (America/Sao_Paulo), no máximo 366 dias." security: - bearerAuth: [] parameters: - schema: type: string format: date description: Primeiro dia (AAAA-MM-DD). example: 2026-01-15 required: false name: start_date in: query - schema: type: string format: date description: Último dia (AAAA-MM-DD). example: 2026-01-15 required: false name: end_date in: query - schema: type: integer minimum: 1 maximum: 366 description: Os últimos N dias, em vez de um intervalo de datas. required: false name: days in: query - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: O uso de IA. content: application/json: schema: $ref: "#/components/schemas/AiUsageResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-ai-usage /v1/rate_limits: get: tags: - Limites de Requisição summary: Consultar limites de requisição description: Os limites de requisição em vigor para a organização, se são personalizados (definidos pela equipe Kobana) e os padrões da plataforma. Somente leitura. security: - bearerAuth: [] responses: "200": description: Os limites. content: application/json: schema: $ref: "#/components/schemas/RateLimitsResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-rate-limits parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/portal_user_mappings: get: tags: - Usuários do Portal summary: Consultar mapeamento de usuários do portal description: A entidade que alimenta os usuários do portal do workspace (`mapping`, `null` se nenhuma, com o resultado da última sincronização) e as entidades que podem ser mapeadas, com seus campos. security: - bearerAuth: [] responses: "200": description: O mapeamento. content: application/json: schema: $ref: "#/components/schemas/PortalUserMappingGetResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-portal-user-mappings parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier put: tags: - Usuários do Portal summary: Mapear entidade aos usuários do portal description: "Mapeia uma entidade: um usuário do portal por e-mail dos seus registros, com o ID do titular vindo de um campo. Substitui o mapeamento anterior e sincroniza na hora (devolve `stats`); as próximas sincronizações da entidade mantêm os usuários em dia." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PortalUserMappingUpdateRequest" responses: "200": description: O mapeamento salvo e o resultado da sincronização. content: application/json: schema: $ref: "#/components/schemas/PortalUserMappingUpdateResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: "Entidade ou campo inválido (ex.: entidade que sincroniza no acesso)." content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-portal-user-mappings parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier delete: tags: - Usuários do Portal summary: Remover mapeamento de usuários do portal description: Para de sincronizar; os usuários já criados continuam. security: - bearerAuth: [] responses: "200": description: "Mapeamento removido (`deleted: false` se não havia)." content: application/json: schema: $ref: "#/components/schemas/PortalUserMappingDeleteResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-portal-user-mappings parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/assets: get: tags: - Arquivos summary: Listar arquivos description: A biblioteca de arquivos do workspace — imagens e documentos que o portal mostra ou oferece para download. Ordenável por `created_at` (padrão), `name` ou `size_bytes`. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Página (começa em 1). Padrão: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Itens por página. Padrão: `20`. Máximo: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Campo de ordenação. Padrão depende do recurso. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Direção da ordenação. Padrão: `desc`." required: false name: sort_order in: query - schema: type: string enum: - image - document - other description: "Filtra pelo tipo: `image`, `document` ou `other`." required: false name: kind in: query - schema: type: string enum: - public - restricted - private description: "Quem pode baixar: `public` (qualquer pessoa com o link), `restricted` (usuários logados no portal do workspace) ou `private` (só membros do dashboard). Arquivos novos começam `restricted`." required: false name: visibility in: query - schema: type: string description: Trecho do nome do arquivo (sem diferenciar maiúsculas). required: false name: search in: query - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Lista paginada de arquivos. content: application/json: schema: $ref: "#/components/schemas/AssetListResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-assets post: tags: - Arquivos summary: Adicionar arquivo description: "Registra um arquivo na biblioteca, de um de dois jeitos: o `key` de um arquivo já enviado pela URL de `POST /assets/presign`, ou o próprio conteúdo em `content_base64`. O arquivo começa `restricted`, a menos que `visibility` diga outra coisa. Dispara o webhook `asset.created`." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/AssetCreateRequest" responses: "201": description: Arquivo registrado. content: application/json: schema: $ref: "#/components/schemas/AssetResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-assets parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/assets/presign: post: tags: - Arquivos summary: Gerar URL de envio description: Uma URL assinada e de curta duração para enviar o arquivo direto ao storage com `PUT` — o caminho para arquivos acima do limite de 2 MB do corpo. Depois do `PUT`, registre o arquivo em `POST /assets` com o `key` devolvido. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/AssetPresignRequest" responses: "200": description: URL de envio gerada. content: application/json: schema: $ref: "#/components/schemas/AssetPresignResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-assets-presign parameters: - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/assets/{id}: get: tags: - Arquivos summary: Consultar arquivo description: Um arquivo da biblioteca, com o link, a visibilidade, o tipo e o tamanho. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID do arquivo (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: O arquivo. content: application/json: schema: $ref: "#/components/schemas/AssetResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-assets-id patch: tags: - Arquivos summary: Atualizar arquivo description: Renomeia o arquivo, troca o texto alternativo ou a visibilidade. Tornar público abre a URL do storage para qualquer pessoa; `restricted` ou `private` a fecha. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID do arquivo (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier requestBody: content: application/json: schema: $ref: "#/components/schemas/AssetUpdateRequest" responses: "200": description: Arquivo atualizado. content: application/json: schema: $ref: "#/components/schemas/AssetResponse" "400": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Corpo da requisição falhou na validação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-assets-id delete: tags: - Arquivos summary: Remover arquivo description: Tira o arquivo da biblioteca. O arquivo guardado continua no storage, para que links já publicados não quebrem. Dispara o webhook `asset.deleted`. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID do arquivo (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Arquivo removido. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-assets-id /v1/assets/{id}/download: get: tags: - Arquivos summary: Baixar arquivo description: O conteúdo do arquivo, qualquer que seja a visibilidade, com o `Content-Type` dele. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID do arquivo (UUID). required: true name: id in: path - schema: type: string enum: - "true" - "false" description: "Com `true`, imagens e PDF vêm para exibição no lugar (`Content-Disposition: inline`); os demais tipos vêm sempre como anexo." required: false name: inline in: query - name: User-Agent in: header required: true description: "Identificação do integrador. Inclua nome e e-mail de contato — ex.: `Kevin Mitnick `. Usado para suporte e auditoria." schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Chave única (UUID v4 recomendado) para reexecutar a mesma requisição sem efeitos colaterais. Requisições com a mesma chave em 24h retornam o resultado original. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Superfície que faz a chamada: `dashboard`, `api`, `cli`, `mcp` ou `other`. Fica gravada em `created_via` / `updated_via` dos registros criados ou alterados. Sem o cabeçalho, vale `api`. Valor desconhecido retorna 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace em que a chamada atua: o `id` ou o `public_id` mostrados em Workspaces no dashboard. Dentro da organização do token, os dados ficam em workspaces. Pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele retorna `400 workspace_required`. Um workspace que não é da organização retorna `403 unknown_workspace`. Com um token de pessoa, só os workspaces a que ela tem acesso (proprietários da organização alcançam todos); os demais retornam `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Nome do aplicativo que faz a chamada. Obrigatório quando `X-Request-Source` é `other` (até 100 caracteres); ignorado nos demais casos. Fica gravado em `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: O conteúdo do arquivo. content: application/octet-stream: schema: type: string format: binary "401": description: Token bearer ausente ou inválido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token válido, porém sem permissão para esta operação. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Recurso não encontrado na organização atual. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Limite de requisições excedido. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Erro inesperado no servidor. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-assets-id-download webhooks: {}