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 o portal (construtor, páginas, marca, acesso e domínios), os usuários do portal, conectores, entidades, arquivos, webhooks e a equipe da organização. 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. ## Autenticação Toda requisição leva o token, que diz qual **organização** você é. Quando a organização tem mais de um **workspace**, leva também o cabeçalho `X-Workspace-Id`, que diz em qual deles agir. ``` Authorization: Bearer X-Workspace-Id: ``` ### O token Access token da **Conta Kobana**: um JWT assinado em **RS256** pelo servidor de autorização da Kobana (`account.kobana.com.br`). Esta API só o verifica — não emite token nenhum. | Claim | Papel | | :--- | :--- | | **`org`** | **O tenant.** A conta Kobana em cujo nome o token age — é o que decide quais dados o token alcança. Obrigatória. | | `sub` | A **pessoa** que autorizou. Existe para auditoria e **não** delimita nada. | | `scope` | Lista separada por espaços (ex.: `dashboards/users write`). Recurso sem verbo é leitura; escrever exige também `write`. | | `jti` | Identificador do token, usado para revogação. | | `iss` / `aud` / `exp` | Emissor, destinatário e expiração (obrigatória). | ⚠️ O tenant é `org`, nunca `sub`. São espaços de identificadores diferentes: um id de pessoa jamais corresponde a uma organização, então um token sem `org` é recusado. ### O cabeçalho `X-Workspace-Id` Uma organização pode ter **vários workspaces**, e toda rota desta API responde por exatamente **um**. Enquanto a organização tem um único workspace, o cabeçalho pode ficar de fora; a partir do segundo, é obrigatório. Aceita o `id` ou o `public_id` do workspace, ambos na página **Workspaces** do dashboard. Ele é um **seletor, nunca uma permissão**: o workspace informado é conferido contra a organização do token, e um token emitido para uma pessoa só alcança os workspaces a que ela tem acesso. | Situação | Resposta | | :--- | :--- | | Cabeçalho ausente com mais de um workspace | `400` `workspace_required` | | Workspace de outra organização, inexistente, ou id malformado | `403` `unknown_workspace` | | A pessoa do token não tem acesso ao workspace | `403` `workspace_access_denied` | | `org` não corresponde a nenhuma organização | `403` `unknown_organization` | | Escopo insuficiente para a operação | `403` `insufficient_scope` | ### Exemplo ```bash curl https://api.dashboards.kobana.com.br/v1/portal_users \ -H "Authorization: Bearer $KOBANA_TOKEN" \ -H "X-Workspace-Id: $KOBANA_WORKSPACE_ID" ``` Para testes em linha de comando, exporte os dois: `export KOBANA_TOKEN=xxxxxxxx` e `export KOBANA_WORKSPACE_ID=xxxxxxxx`, e cole os comandos da documentação no terminal. ## 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. | ## Ambientes | Ambiente | Base URL | | :--- | :--- | | **Produção** | `https://api.dashboards.kobana.com.br` | | **Sandbox** | `https://api.dashboards.sandbox.kobana.com.br` | Cada ambiente exige seu próprio token — o de um não vale no outro. ## Listagem e Paginação Todos os endpoints de listagem usam **paginação por número de página**: ``` GET /v1/portal_users?page=2&per_page=50&sort_by=created_at&sort_order=desc ``` `per_page` vai até **100** (padrão `20`). A resposta traz os itens em `data` e, em `meta`, `total`, `page`, `per_page` e `total_pages`. ## Idempotência Requisições `POST`, `PUT` e `PATCH` aceitam o cabeçalho `X-Idempotency-Key`. Reenvios com a mesma chave em até **24h** retornam o resultado original sem repetir a operação — seguro para retry em caso de falha de rede. ``` X-Idempotency-Key: ``` ## 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). ## Spec OpenAPI Importe a spec no Postman ou Insomnia para ter uma coleção pronta que sempre reflete a API atual: - **YAML:** `https://api.dashboards.kobana.com.br/v1/openapi.yaml` - **JSON:** `https://api.dashboards.kobana.com.br/v1/openapi.json` 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`. Ao reativar, o usuário volta ao status que tinha antes da suspensão (quem ainda não tinha confirmado o e-mail continua pendente)." unlock: type: boolean enum: - true description: "`true` encerra o bloqueio de login (muitas senhas erradas): zera as tentativas e libera o login. 400 quando o usuário não está bloqueado." 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 PortalUserActivityResponse: type: object properties: data: type: object properties: portal_user_id: type: string format: uuid period_days: type: integer logins: type: integer description: Logins no portal, desde sempre. views: type: integer description: Páginas do portal abertas, desde sempre. distinct_pages: type: integer description: Páginas diferentes abertas, desde sempre. last_activity_at: type: - string - "null" format: date-time description: Login ou visita mais recente; `null` se o usuário nunca acessou. series: type: array items: type: object properties: date: type: string views: type: integer logins: type: integer required: - date - views - logins description: Um ponto por dia do período (`YYYY-MM-DD`, horário de São Paulo), do mais antigo ao mais recente, com zeros nos dias sem atividade. top_pages: type: array items: type: object properties: path: type: string page_name: type: - string - "null" views: type: integer required: - path - page_name - views description: As 5 páginas mais abertas, da mais aberta à menos. `page_name` é `null` quando a página não é publicada (a inicial padrão). required: - portal_user_id - period_days - logins - views - distinct_pages - last_activity_at - series - top_pages required: - data PortalUserActivityEntry: oneOf: - type: object properties: kind: type: string enum: - login id: type: string format: uuid at: type: string format: date-time method: type: string required: - kind - id - at - method - type: object properties: kind: type: string enum: - page_view id: type: string format: uuid at: type: string format: date-time path: type: string page_name: type: - string - "null" required: - kind - id - at - path - page_name PortalUserActivityTimelineResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/PortalUserActivityEntry" meta: type: object properties: limit: type: integer has_more: type: boolean next_before: type: - string - "null" format: date-time required: - limit - has_more - next_before required: - data - meta 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 - suspended description: "Novo status: `suspended` suspende o membro, `active` reativa. Um convite pendente não muda por aqui: ele fica ativo quando a pessoa convidada entra. Outros valores recebem 422." 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 - "null" format: uuid description: Fonte de dados (conector) de onde a entidade lê; `null` numa entidade `push` (sem conexão). integration_name: type: - string - "null" kind: type: string enum: - openapi - mcp - database - push description: "Tipo da fonte de dados: `openapi`, `mcp`, `database` ou `push` (sem conexão)." source_kind: type: string enum: - operation - sql - join - push description: "`operation` (endpoint, tool ou tabela), `sql` (consulta em banco SQL), `join` (relação entre duas entidades) ou `push` (sem conexão: os registros são enviados por importação de CSV, API ou MCP)." 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 - "null" format: uuid description: ID da sincronização enfileirada; `null` numa relação entre entidades sem conexão, refeita na hora. 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. Omitido com `source_kind: "push"`.' 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. Omitido com `source_kind: "push"`.' 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. source_kind: type: string enum: - push description: "`push`: entidade sem conexão — sem `integration_id`, `operation_id` ou `sql`. O `source_path` de cada campo vale a chave do campo quando omitido (a propriedade que cada registro enviado traz) e `identifier_field_key` é obrigatório: é por ele que um registro enviado de novo atualiza o existente." 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: - 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 EntityRecordsPushRequest: type: object properties: records: type: array items: type: object additionalProperties: {} minItems: 1 maxItems: 1000 description: Os registros (até 1000 por chamada), cada um um objeto com as propriedades que os campos leem (`source_path`). O identificador é obrigatório em cada um. example: - id: "42" nome: Ana Souza valor: 1250.5 cliente_id: C-001 mode: type: string enum: - upsert - replace description: "`upsert` (padrão) mantém os registros não enviados; `replace` remove os que a chamada não traz — o envio passa a ser o conjunto inteiro." required: - records EntityRecordsImportRequest: type: object properties: content: type: string description: "O texto do CSV: primeira linha com os nomes das colunas (o `source_path` dos campos), separador `,` ou `;`, até 20.000 linhas. Envie este ou `content_base64`." example: |- id;nome;valor 42;Ana Souza;1250,50 content_base64: type: string description: O arquivo CSV em base64 (UTF-8). mode: type: string enum: - upsert - replace description: "`upsert` (padrão) mantém os registros não enviados; `replace` remove os que a chamada não traz — o envio passa a ser o conjunto inteiro." EntityRecordsPushResponse: type: object properties: data: type: object properties: received: type: integer description: Registros enviados (linhas do CSV). created: type: integer updated: type: integer unchanged: type: integer deleted: type: integer description: Removidos por não estarem num envio `replace`. errors: type: array items: type: object properties: row: type: integer index: type: integer error: type: string required: - error description: "Registros recusados: `row` (linha do CSV) ou `index` (posição em `records`) e o motivo." records_count: type: integer description: Registros da entidade depois do envio. missing_columns: type: array items: type: string description: "CSV: colunas que os campos leem e o arquivo não tem (esses campos ficam vazios)." required: - received - created - updated - unchanged - deleted - errors - records_count required: - data EntityRecordDeletedResponse: type: object properties: data: type: object properties: deleted: type: object properties: id: type: string format: uuid external_id: type: string required: - id - external_id required: - deleted required: - data 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 /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 /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 /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. Obrigatório quando `issuer_url` muda (outro host, porta ou caminho): sem ele a alteração é recusada com 422 `CLIENT_SECRET_REQUIRED_FOR_ISSUER_CHANGE`, para o secret guardado não ser enviado a outro provedor." 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)." tenant_id: type: - string - "null" description: Tenant ID dos usuários do portal que veem o arquivo — todos os usuários do mesmo tenant veem os mesmos arquivos, nos blocos Arquivos do Usuário. `null` = arquivo do workspace, sem tenant. type_id: type: - string - "null" format: uuid description: "Tipo do arquivo (`GET /asset_types`: Propostas, Contratos…). Um bloco Arquivos do Usuário lista os tipos que escolhe; um arquivo com tipo e sem tenant aparece para todos os usuários nos blocos desse tipo. `null` = sem tipo." tags: type: array items: type: string description: Tags do arquivo. 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 - tenant_id - type_id - tags - 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`." tenant_id: type: - string - "null" description: Tenant ID dos usuários do portal que veem o arquivo — todos os usuários do mesmo tenant veem os mesmos arquivos, nos blocos Arquivos do Usuário. `null` = arquivo do workspace, sem tenant. type_id: type: - string - "null" format: uuid description: "Tipo do arquivo (`GET /asset_types`: Propostas, Contratos…). Um bloco Arquivos do Usuário lista os tipos que escolhe; um arquivo com tipo e sem tenant aparece para todos os usuários nos blocos desse tipo. `null` = sem tipo." tags: type: array items: type: string description: Tags do arquivo (até 20, cada uma com até 50 caracteres; repetidas são ignoradas). Substitui as atuais. 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`." tenant_id: type: - string - "null" description: Tenant ID dos usuários do portal que veem o arquivo — todos os usuários do mesmo tenant veem os mesmos arquivos, nos blocos Arquivos do Usuário. `null` = arquivo do workspace, sem tenant. type_id: type: - string - "null" format: uuid description: "Tipo do arquivo (`GET /asset_types`: Propostas, Contratos…). Um bloco Arquivos do Usuário lista os tipos que escolhe; um arquivo com tipo e sem tenant aparece para todos os usuários nos blocos desse tipo. `null` = sem tipo." tags: type: array items: type: string description: Tags do arquivo (até 20, cada uma com até 50 caracteres; repetidas são ignoradas). Substitui as atuais. 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 AssetTypeV1: type: object properties: id: type: string format: uuid name: type: string description: Nome do tipo (Propostas, Contratos…), único no workspace sem diferenciar maiúsculas; até 100 caracteres. asset_count: type: integer description: Quantos arquivos têm este tipo (só na listagem). created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - name - created_at - updated_at AssetTypeResponse: type: object properties: data: $ref: "#/components/schemas/AssetTypeV1" required: - data AssetTypeListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/AssetTypeV1" required: - data AssetTypeRequest: type: object properties: name: type: string description: Nome do tipo (Propostas, Contratos…), único no workspace sem diferenciar maiúsculas; até 100 caracteres. required: - name ChecklistV1: type: object properties: id: type: string description: ID da checklist (id do bloco). title: type: string page_stable_id: type: string description: A página do portal publicado onde a checklist está. page_path: type: string page_name: type: string stages: type: array items: type: object properties: id: type: string title: type: string tasks: type: array items: type: object properties: id: type: string title: type: string description: type: string due_date: type: - string - "null" description: YYYY-MM-DD assignee: type: - string - "null" action: type: object properties: type: type: string enum: - none - link - file_request - attachment - video label: type: - string - "null" url: type: - string - "null" file_name: type: - string - "null" required: - type - label - url - file_name description: "O que a tarefa oferece: `link` (botão para `url`), `file_request` (o cliente envia um arquivo), `attachment` (arquivo anexado, em `url`), `video` (YouTube ou Loom) ou `none`." required: - id - title - description - due_date - assignee - action required: - id - title - tasks description: Etapas, em ordem, com as tarefas visíveis a todos (as ocultas nunca saem do builder). required: - id - title - page_stable_id - page_path - page_name - stages ChecklistResponse: type: object properties: data: $ref: "#/components/schemas/ChecklistV1" required: - data ChecklistListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/ChecklistV1" required: - data ChecklistProgressV1: type: object properties: checklist_id: type: string title: type: string tenant_id: type: - string - "null" description: Tenant ID dos usuários do portal donos do progresso — todos os usuários do mesmo tenant veem a mesma checklist. Informe este ou `portal_user_id`. tenant_key: type: string description: "De quem é o progresso: o tenant ID, ou `user:` para um usuário sem tenant." portal_user_id: type: - string - "null" description: "Um usuário do portal (id ou external_id): vale o progresso do tenant dele (um usuário sem tenant tem uma checklist só dele). Informe este ou `tenant_id`." done: type: integer total: type: integer stages: type: array items: type: object properties: id: type: string title: type: string done: type: integer total: type: integer tasks: type: array items: type: object properties: id: type: string title: type: string status: type: string enum: - pending - in_progress - done description: "`pending`, `in_progress` ou `done`. Uma tarefa que ninguém tocou é `pending`." completed_at: type: - string - "null" format: date-time file: type: - object - "null" properties: name: type: string size_bytes: type: integer content_type: type: string uploaded_at: type: string format: date-time download_url: type: string required: - name - size_bytes - content_type - uploaded_at - download_url description: O arquivo enviado a uma tarefa `file_request`, com o caminho da API para baixá-lo. updated_by_portal_user_id: type: - string - "null" format: uuid description: Usuário do portal que mudou a tarefa por último; `null` quando foi a API ou ninguém. updated_at: type: - string - "null" format: date-time required: - id - title - status - completed_at - file - updated_by_portal_user_id - updated_at required: - id - title - done - total - tasks required: - checklist_id - title - tenant_id - tenant_key - portal_user_id - done - total - stages ChecklistProgressResponse: type: object properties: data: $ref: "#/components/schemas/ChecklistProgressV1" required: - data ChecklistProgressUpdateRequest: type: object properties: tenant_id: type: string description: Tenant ID dos usuários do portal donos do progresso — todos os usuários do mesmo tenant veem a mesma checklist. Informe este ou `portal_user_id`. portal_user_id: type: string description: "Um usuário do portal (id ou external_id): vale o progresso do tenant dele (um usuário sem tenant tem uma checklist só dele). Informe este ou `tenant_id`." task_ids: type: array items: type: string minItems: 1 maxItems: 100 status: type: string enum: - pending - in_progress - done description: "`pending`, `in_progress` ou `done`. Uma tarefa que ninguém tocou é `pending`." required: - task_ids - status ChecklistFileUploadRequest: type: object properties: tenant_id: type: string description: Tenant ID dos usuários do portal donos do progresso — todos os usuários do mesmo tenant veem a mesma checklist. Informe este ou `portal_user_id`. portal_user_id: type: string description: "Um usuário do portal (id ou external_id): vale o progresso do tenant dele (um usuário sem tenant tem uma checklist só dele). Informe este ou `tenant_id`." task_id: type: string name: type: string content_base64: type: string description: O conteúdo do arquivo em base64 (até o limite de 2 MB da requisição). content_type: type: string required: - task_id - name - content_base64 ChecklistFileResponse: type: object properties: data: type: object properties: task_id: type: string file: type: - object - "null" properties: name: type: string size_bytes: type: integer content_type: type: string uploaded_at: type: string format: date-time required: - name - size_bytes - content_type - uploaded_at required: - task_id - file required: - data CommentV1: type: object properties: id: type: string format: uuid tenant_key: type: string description: "De quem é a conversa: o Tenant ID dos usuários do portal, ou `user:` para um usuário sem tenant." body: type: string description: A mensagem (até 5000 caracteres). internal: type: boolean description: "Nota interna: só a equipe vê (dashboard, API, MCP); o portal nunca mostra." author_type: type: string enum: - portal_user - member - api description: "Quem escreveu: `portal_user` (usuário do portal), `member` (membro da equipe) ou `api` (integração)." author_name: type: string description: Nome mostrado ao lado da mensagem. Na criação, o padrão é o e-mail do operador do token ou "Equipe". author_email: type: - string - "null" portal_user_id: type: - string - "null" format: uuid dashboard_user_id: type: - string - "null" format: uuid created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - tenant_key - body - internal - author_type - author_name - author_email - portal_user_id - dashboard_user_id - created_at - updated_at CommentResponse: type: object properties: data: $ref: "#/components/schemas/CommentV1" required: - data CommentListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/CommentV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta CommentCreateRequest: type: object properties: tenant_id: type: string description: Tenant ID dos usuários do portal donos da conversa — todos os usuários do mesmo tenant veem os mesmos comentários. Informe este ou `portal_user_id`. portal_user_id: type: string description: "Um usuário do portal (id ou external_id): vale a conversa do tenant dele (um usuário sem tenant tem uma conversa só dele). Informe este ou `tenant_id`." body: type: string minLength: 1 maxLength: 5000 description: A mensagem (até 5000 caracteres). internal: type: boolean description: "Nota interna: só a equipe vê (dashboard, API, MCP); o portal nunca mostra." author_name: type: string description: Nome mostrado ao lado da mensagem. Na criação, o padrão é o e-mail do operador do token ou "Equipe". required: - body PortalUserRemovedResponse: type: object properties: data: type: object properties: deleted: type: boolean example: true outcome: type: string enum: - deleted - suspended - already_suspended description: "`deleted` (convite excluído), `suspended` (usuário suspenso) ou `already_suspended` (nada mudou)." example: suspended required: - deleted - outcome 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. PortalBuilderToolReadResponse: type: object properties: data: type: object additionalProperties: {} required: - data PortalBuilderToolWriteResponse: type: object properties: data: type: object properties: revision: type: integer description: "Trava otimista do rascunho: envie-a no próximo salvamento ou publicação." required: - revision additionalProperties: {} required: - data PortalBuilderRestoreResponse: type: object properties: data: type: object properties: revision: type: integer description: "Trava otimista do rascunho: envie-a no próximo salvamento ou publicação." restored_number: type: integer pages: type: integer required: - revision - restored_number - pages required: - data PortalBuilderThemeResponse: type: object properties: data: type: object properties: revision: type: integer description: "Trava otimista do rascunho: envie-a no próximo salvamento ou publicação." theme_changed: type: boolean colors: type: integer required: - revision - theme_changed - colors required: - data PortalBuilderThemeRequest: type: object properties: light: type: object properties: primary: type: string pattern: ^#[0-9a-fA-F]{6}$ primary_foreground: type: string pattern: ^#[0-9a-fA-F]{6}$ accent: type: string pattern: ^#[0-9a-fA-F]{6}$ background: type: string pattern: ^#[0-9a-fA-F]{6}$ foreground: type: string pattern: ^#[0-9a-fA-F]{6}$ card: type: string pattern: ^#[0-9a-fA-F]{6}$ muted: type: string pattern: ^#[0-9a-fA-F]{6}$ muted_foreground: type: string pattern: ^#[0-9a-fA-F]{6}$ border: type: string pattern: ^#[0-9a-fA-F]{6}$ dark: type: object properties: primary: type: string pattern: ^#[0-9a-fA-F]{6}$ primary_foreground: type: string pattern: ^#[0-9a-fA-F]{6}$ accent: type: string pattern: ^#[0-9a-fA-F]{6}$ background: type: string pattern: ^#[0-9a-fA-F]{6}$ foreground: type: string pattern: ^#[0-9a-fA-F]{6}$ card: type: string pattern: ^#[0-9a-fA-F]{6}$ muted: type: string pattern: ^#[0-9a-fA-F]{6}$ muted_foreground: type: string pattern: ^#[0-9a-fA-F]{6}$ border: type: string pattern: ^#[0-9a-fA-F]{6}$ 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: Excluir usuário do portal description: Convites pendentes são excluídos definitivamente; os demais usuários são suspensos e suas sessões encerradas. Um usuário já suspenso não muda. `outcome` diz o que aconteceu. 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 da exclusão. content: application/json: schema: $ref: "#/components/schemas/PortalUserRemovedResponse" "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}/activity: get: tags: - Usuários do Portal summary: Consultar a atividade do usuário do portal description: "Analytics de uso de um usuário do portal: logins e páginas visitadas (desde sempre), páginas diferentes, a atividade mais recente, uma série diária de visitas e logins nos últimos `days` dias (dias de São Paulo) e as páginas mais abertas. As entradas individuais ficam em `GET /portal_users/{id}/activity/timeline`." security: - bearerAuth: [] parameters: - schema: type: string description: UUID do usuário do portal ou seu `external_id`. required: true name: id in: path - schema: type: integer minimum: 1 maximum: 365 description: "Dias cobertos pela `series`, incluindo hoje (1 a 365). Padrão: 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: Resumo da atividade do usuário. content: application/json: schema: $ref: "#/components/schemas/PortalUserActivityResponse" "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-activity /v1/portal_users/{id}/activity/timeline: get: tags: - Usuários do Portal summary: Listar a linha do tempo do usuário do portal description: "Logins (`kind: login`, com o `method` usado: `credentials`, `magic-link` ou `sso`) e páginas abertas (`kind: page_view`, com `path` e `page_name`), da mais recente à mais antiga. Paginação por cursor: envie `meta.next_before` como `before` para a página seguinte; `null` indica que não há mais. Acessos de um operador visualizando o portal como o usuário não entram." security: - bearerAuth: [] parameters: - schema: type: string description: UUID do usuário do portal ou seu `external_id`. required: true name: id in: path - schema: type: string format: date-time description: "Instante ISO 8601: só entradas mais antigas que ele." required: false name: before in: query - schema: type: integer minimum: 1 maximum: 100 description: "Entradas por página (1 a 100). Padrão: 20." required: false name: limit 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: Uma página da linha do tempo. content: application/json: schema: $ref: "#/components/schemas/PortalUserActivityTimelineResponse" "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-activity-timeline /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`. Ao atualizar, com um token de pessoa, ela precisa ter acesso a todos os workspaces em que o membro trabalha (ou ser proprietária da organização); caso contrário, 403. 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. Com um token de pessoa, ela precisa ter acesso a todos os workspaces em que o membro trabalha (ou ser proprietária da organização); caso contrário, 403. 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. Com um token de pessoa, ela precisa ter acesso a todos os workspaces em que o membro trabalha (ou ser proprietária da organização); caso contrário, 403. 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: string enum: - "true" - "false" - all description: Filtra por funções ativas (`true`, o padrão), inativas (`false`) ou todas (`all`). 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 `_`. Com um token de pessoa, ela precisa ter acesso a todos os workspaces da organização (ou ser proprietária): um papel vale em todos eles. Caso contrário, 403." 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`. Com um token de pessoa, ela precisa ter acesso a todos os workspaces da organização (ou ser proprietária): um papel vale em todos eles. Caso contrário, 403." 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. Com um token de pessoa, ela precisa ter acesso a todos os workspaces da organização (ou ser proprietária): um papel vale em todos eles. Caso contrário, 403." 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. Com um token de pessoa, ela precisa ter acesso a todos os workspaces da organização (ou ser proprietária): um papel vale em todos eles. Caso contrário, 403." 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. Recusado (409) enquanto uma entidade lê a fonte: remova as entidades antes. 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" "409": description: Uma ou mais entidades leem esta fonte de dados. 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 post: tags: - Entidades summary: Enviar registros description: 'Envia registros para uma entidade sem conexão (`source_kind: "push"`): cada um é gravado pelo identificador — enviado de novo, é atualizado; sem mudança, não é reescrito. Relações e usuários do portal que dependem da entidade são atualizados em seguida. 422 numa entidade que lê de uma conexã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/EntityRecordsPushRequest" responses: "200": description: Quantos registros foram criados, alterados, mantidos e removidos, e os recusados. content: application/json: schema: $ref: "#/components/schemas/EntityRecordsPushResponse" "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-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 delete: tags: - Entidades summary: Remover registro description: "Remove um registro de uma entidade sem conexão. 422 numa entidade que lê de uma conexão: os registros dela saem quando saem da origem." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID (UUID) da entidade. required: true name: id in: path - schema: type: string description: ID (UUID) do registro, ou o valor do identificador com que ele foi enviado. 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 removido. content: application/json: schema: $ref: "#/components/schemas/EntityRecordDeletedResponse" "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-entities-id-records-record-id /v1/entities/{id}/records/import: post: tags: - Entidades summary: Importar CSV description: "Importa um CSV para uma entidade sem conexão: um registro por linha, cada coluna lida por um campo convertida para o tipo dele (números, datas, booleanos). Linhas sem identificador são recusadas e listadas pelo número da linha (a 1 é o cabeçalho)." 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/EntityRecordsImportRequest" responses: "200": description: Quantos registros foram criados, alterados, mantidos e removidos, e os recusados. content: application/json: schema: $ref: "#/components/schemas/EntityRecordsPushResponse" "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-records-import /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/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-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/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 /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-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/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-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/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-builder-versions-number /v1/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-builder-versions-number-rollback /v1/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-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/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-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/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-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/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 /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-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/builder/tools/list_block_types: get: tags: - Construtor do Portal summary: Listar os tipos de bloco description: "Lists the block catalog: every block type the portal can render, with what it is for. Only these types exist." security: - bearerAuth: [] responses: "200": description: O que a ferramenta leu, em `data`. content: application/json: schema: $ref: "#/components/schemas/PortalBuilderToolReadResponse" "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 ferramenta recusou o passo (`BUILDER_OPERATION_REJECTED`): tipo de bloco inexistente, props que não passam no esquema do bloco, caminho em uso, entidade desconhecida… A mensagem diz o motivo e nada é salvo." 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-builder-tools-list-block-types 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/builder/tools/describe_block_type: get: tags: - Construtor do Portal summary: Descrever um tipo de bloco description: "The props of one block type: JSON Schema, defaults and slots. Read it before inserting or changing a block you have not used yet." security: - bearerAuth: [] parameters: - schema: type: string description: Block type, e.g. DataTable. required: true description: Block type, e.g. DataTable. name: type 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 que a ferramenta leu, em `data`. content: application/json: schema: $ref: "#/components/schemas/PortalBuilderToolReadResponse" "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 ferramenta recusou o passo (`BUILDER_OPERATION_REJECTED`): tipo de bloco inexistente, props que não passam no esquema do bloco, caminho em uso, entidade desconhecida… A mensagem diz o motivo e nada é salvo." 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-builder-tools-describe-block-type /v1/builder/tools/list_actions: get: tags: - Construtor do Portal summary: Listar as ações do botão description: "What an ActionButton can do (its actionType): open a link (a portal page or a URL) or fire a webhook, and the {{variables}} its webhook URL, headers and body may use." security: - bearerAuth: [] responses: "200": description: O que a ferramenta leu, em `data`. content: application/json: schema: $ref: "#/components/schemas/PortalBuilderToolReadResponse" "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 ferramenta recusou o passo (`BUILDER_OPERATION_REJECTED`): tipo de bloco inexistente, props que não passam no esquema do bloco, caminho em uso, entidade desconhecida… A mensagem diz o motivo e nada é salvo." 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-builder-tools-list-actions 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/builder/tools/get_theme: get: tags: - Construtor do Portal summary: Consultar as cores do tema description: "The colors of the portal pages (the Visual tab of the draft), in hex, for light and dark mode: what each color is for and its current value." security: - bearerAuth: [] responses: "200": description: O que a ferramenta leu, em `data`. content: application/json: schema: $ref: "#/components/schemas/PortalBuilderToolReadResponse" "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 ferramenta recusou o passo (`BUILDER_OPERATION_REJECTED`): tipo de bloco inexistente, props que não passam no esquema do bloco, caminho em uso, entidade desconhecida… A mensagem diz o motivo e nada é salvo." 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-builder-tools-get-theme 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/builder/tools/list_pages: get: tags: - Construtor do Portal summary: Listar as páginas do rascunho description: "Lists the pages of the draft in menu order: id, name, path, title and block count." security: - bearerAuth: [] responses: "200": description: O que a ferramenta leu, em `data`. content: application/json: schema: $ref: "#/components/schemas/PortalBuilderToolReadResponse" "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 ferramenta recusou o passo (`BUILDER_OPERATION_REJECTED`): tipo de bloco inexistente, props que não passam no esquema do bloco, caminho em uso, entidade desconhecida… A mensagem diz o motivo e nada é salvo." 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-builder-tools-list-pages 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/builder/tools/get_page: get: tags: - Construtor do Portal summary: Consultar uma página do rascunho description: "One page of the draft: its settings (name, path, title, SEO) and its block tree, each block with id, type, props and slots." security: - bearerAuth: [] parameters: - schema: type: string minLength: 1 description: Page id (list_pages). required: true description: Page id (list_pages). name: page_id 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 que a ferramenta leu, em `data`. content: application/json: schema: $ref: "#/components/schemas/PortalBuilderToolReadResponse" "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 ferramenta recusou o passo (`BUILDER_OPERATION_REJECTED`): tipo de bloco inexistente, props que não passam no esquema do bloco, caminho em uso, entidade desconhecida… A mensagem diz o motivo e nada é salvo." 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-builder-tools-get-page /v1/builder/tools/read_asset: get: tags: - Construtor do Portal summary: Ler o conteúdo de um arquivo description: "Opens a file of the Assets library to look at its content: an image or a PDF is shown to you, a text file (txt, csv, json, md, xml) or an .xlsx spreadsheet comes as text. Word/PowerPoint/zip cannot be read (only their details)." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Asset id (list_assets, or the asset_id of a file sent in the chat). required: true description: Asset id (list_assets, or the asset_id of a file sent in the chat). name: asset_id 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 que a ferramenta leu, em `data`. content: application/json: schema: $ref: "#/components/schemas/PortalBuilderToolReadResponse" "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 ferramenta recusou o passo (`BUILDER_OPERATION_REJECTED`): tipo de bloco inexistente, props que não passam no esquema do bloco, caminho em uso, entidade desconhecida… A mensagem diz o motivo e nada é salvo." 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-builder-tools-read-asset /v1/builder/tools/preview_portal_user_mapping: get: tags: - Construtor do Portal summary: Pré-visualizar o mapeamento de usuários do portal description: "Checks a portal user mapping before saving it with `dashboards_portal_user_mappings_update`: the entity whose records would become the portal users, its tenant ID, e-mail and name fields, how many users that is, and how the tenant IDs match the owners of the other entities' records. Saves nothing." security: - bearerAuth: [] parameters: - schema: type: string minLength: 1 description: Entity key. required: true description: Entity key. name: entity in: query - schema: type: string minLength: 1 description: The value the other entities' owners hold (the owner field of the entity, or its identifier). required: true description: The value the other entities' owners hold (the owner field of the entity, or its identifier). name: tenant_id_field in: query - schema: type: string minLength: 1 description: The field with the customer's e-mail. required: true description: The field with the customer's e-mail. name: email_field in: query - schema: type: string minLength: 1 description: The field with the customer's name, if any. required: false description: The field with the customer's name, if any. name: name_field 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 que a ferramenta leu, em `data`. content: application/json: schema: $ref: "#/components/schemas/PortalBuilderToolReadResponse" "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 ferramenta recusou o passo (`BUILDER_OPERATION_REJECTED`): tipo de bloco inexistente, props que não passam no esquema do bloco, caminho em uso, entidade desconhecida… A mensagem diz o motivo e nada é salvo." 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-builder-tools-preview-portal-user-mapping /v1/builder/tools/create_page: post: tags: - Construtor do Portal summary: Criar uma página description: "Creates a page in the draft and adds it to the portal menu. template: blank (title only), list (title + KPIs + table of `entity`), detail (title + record detail + documents). The title is a PageHeader block: the answer lists the blocks it created — change them with update_block instead of inserting them again." security: - bearerAuth: [] requestBody: content: application/json: schema: type: object properties: name: type: string minLength: 1 maxLength: 200 description: Menu label. path: type: string maxLength: 500 description: Route, e.g. /contratos. Omitted = derived from the name. title: type: string maxLength: 300 description: Browser title; omitted = the name. template: type: string enum: - blank - list - detail default: blank entity: type: string description: Entity the list/detail template binds to. show_in_menu: type: boolean description: Listed in the portal menu (default true); false for a detail page reached by links. position: type: integer minimum: 0 description: Place in the menu; omitted = last. revision: type: integer minimum: 0 description: "A `revision` do rascunho lida por último. Opcional: se enviada e desatualizada, responde 409 e não salva nada." required: - name responses: "200": description: O que a ferramenta fez, em `data`, e a nova `revision` do rascunho (a mesma de antes se nada mudou). content: application/json: schema: $ref: "#/components/schemas/PortalBuilderToolWriteResponse" "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: "A ferramenta recusou o passo (`BUILDER_OPERATION_REJECTED`): tipo de bloco inexistente, props que não passam no esquema do bloco, caminho em uso, entidade desconhecida… A mensagem diz o motivo e nada é salvo." 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-builder-tools-create-page 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/builder/tools/update_page: post: tags: - Construtor do Portal summary: Alterar uma página description: "Changes the settings of a page: menu name, route, browser title, whether it is listed in the portal menu, and SEO / Open Graph tags. Only the fields sent change." security: - bearerAuth: [] requestBody: content: application/json: schema: type: object properties: page_id: type: string minLength: 1 description: Page id (list_pages). name: type: string maxLength: 200 path: type: string maxLength: 500 title: type: string maxLength: 300 show_in_menu: type: boolean description: false = the page stays reachable by links (e.g. a record detail page) but is not in the header menu. seo: type: object properties: description: type: string maxLength: 1000 keywords: type: string maxLength: 1000 robots: type: string maxLength: 100 canonical: type: string maxLength: 2000 og_title: type: string maxLength: 300 og_description: type: string maxLength: 1000 og_image: type: string maxLength: 2000 description: An asset of the workspace (list_assets) or empty; never an outside URL. additionalProperties: false revision: type: integer minimum: 0 description: "A `revision` do rascunho lida por último. Opcional: se enviada e desatualizada, responde 409 e não salva nada." required: - page_id responses: "200": description: O que a ferramenta fez, em `data`, e a nova `revision` do rascunho (a mesma de antes se nada mudou). content: application/json: schema: $ref: "#/components/schemas/PortalBuilderToolWriteResponse" "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: "A ferramenta recusou o passo (`BUILDER_OPERATION_REJECTED`): tipo de bloco inexistente, props que não passam no esquema do bloco, caminho em uso, entidade desconhecida… A mensagem diz o motivo e nada é salvo." 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-builder-tools-update-page 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/builder/tools/delete_page: post: tags: - Construtor do Portal summary: Excluir uma página description: Removes a page (and its blocks) from the draft and from the menu. Only when the operator asks for it. security: - bearerAuth: [] requestBody: content: application/json: schema: type: object properties: page_id: type: string minLength: 1 description: Page id (list_pages). revision: type: integer minimum: 0 description: "A `revision` do rascunho lida por último. Opcional: se enviada e desatualizada, responde 409 e não salva nada." required: - page_id responses: "200": description: O que a ferramenta fez, em `data`, e a nova `revision` do rascunho (a mesma de antes se nada mudou). content: application/json: schema: $ref: "#/components/schemas/PortalBuilderToolWriteResponse" "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: "A ferramenta recusou o passo (`BUILDER_OPERATION_REJECTED`): tipo de bloco inexistente, props que não passam no esquema do bloco, caminho em uso, entidade desconhecida… A mensagem diz o motivo e nada é salvo." 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-builder-tools-delete-page 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/builder/tools/move_page: post: tags: - Construtor do Portal summary: Mover uma página no menu description: Moves a page to another place in the portal menu. security: - bearerAuth: [] requestBody: content: application/json: schema: type: object properties: page_id: type: string minLength: 1 description: Page id (list_pages). position: type: integer minimum: 0 description: 0-based index in the menu. revision: type: integer minimum: 0 description: "A `revision` do rascunho lida por último. Opcional: se enviada e desatualizada, responde 409 e não salva nada." required: - page_id - position responses: "200": description: O que a ferramenta fez, em `data`, e a nova `revision` do rascunho (a mesma de antes se nada mudou). content: application/json: schema: $ref: "#/components/schemas/PortalBuilderToolWriteResponse" "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: "A ferramenta recusou o passo (`BUILDER_OPERATION_REJECTED`): tipo de bloco inexistente, props que não passam no esquema do bloco, caminho em uso, entidade desconhecida… A mensagem diz o motivo e nada é salvo." 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-builder-tools-move-page 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/builder/tools/insert_block: post: tags: - Construtor do Portal summary: Inserir um bloco description: "Inserts a block of the catalog in a page: at the page root, or inside a slot of a Columns/Tabs block (parent_block_id + slot). Props not sent take the defaults." security: - bearerAuth: [] requestBody: content: application/json: schema: type: object properties: page_id: type: string minLength: 1 description: Page id (list_pages). type: type: string description: Block type (list_block_types). props: type: object additionalProperties: {} description: Block props (describe_block_type). Never include id or slot props. parent_block_id: type: - string - "null" description: Columns or Tabs block that receives the new block. slot: type: string description: "Slot of the parent: col1..col3 (Columns) or content (Tabs). Omitted = the first." position: type: integer minimum: 0 description: 0-based index; omitted = at the end. revision: type: integer minimum: 0 description: "A `revision` do rascunho lida por último. Opcional: se enviada e desatualizada, responde 409 e não salva nada." required: - page_id - type responses: "200": description: O que a ferramenta fez, em `data`, e a nova `revision` do rascunho (a mesma de antes se nada mudou). content: application/json: schema: $ref: "#/components/schemas/PortalBuilderToolWriteResponse" "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: "A ferramenta recusou o passo (`BUILDER_OPERATION_REJECTED`): tipo de bloco inexistente, props que não passam no esquema do bloco, caminho em uso, entidade desconhecida… A mensagem diz o motivo e nada é salvo." 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-builder-tools-insert-block 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/builder/tools/update_block: post: tags: - Construtor do Portal summary: Alterar um bloco description: Changes props of a block. Only the props sent change; the result is validated against the block type. security: - bearerAuth: [] requestBody: content: application/json: schema: type: object properties: block_id: type: string minLength: 1 description: Block id (get_page). props: type: object additionalProperties: {} description: Block props (describe_block_type). Never include id or slot props. revision: type: integer minimum: 0 description: "A `revision` do rascunho lida por último. Opcional: se enviada e desatualizada, responde 409 e não salva nada." required: - block_id - props responses: "200": description: O que a ferramenta fez, em `data`, e a nova `revision` do rascunho (a mesma de antes se nada mudou). content: application/json: schema: $ref: "#/components/schemas/PortalBuilderToolWriteResponse" "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: "A ferramenta recusou o passo (`BUILDER_OPERATION_REJECTED`): tipo de bloco inexistente, props que não passam no esquema do bloco, caminho em uso, entidade desconhecida… A mensagem diz o motivo e nada é salvo." 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-builder-tools-update-block 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/builder/tools/move_block: post: tags: - Construtor do Portal summary: Mover um bloco description: "Moves a block inside its page: to another position at the root (parent_block_id null) or into a slot of a Columns/Tabs block." security: - bearerAuth: [] requestBody: content: application/json: schema: type: object properties: block_id: type: string minLength: 1 description: Block id (get_page). parent_block_id: type: - string - "null" description: Columns/Tabs block to move into; null or omitted = the page root. slot: type: string position: type: integer minimum: 0 description: 0-based index in the target. revision: type: integer minimum: 0 description: "A `revision` do rascunho lida por último. Opcional: se enviada e desatualizada, responde 409 e não salva nada." required: - block_id - position responses: "200": description: O que a ferramenta fez, em `data`, e a nova `revision` do rascunho (a mesma de antes se nada mudou). content: application/json: schema: $ref: "#/components/schemas/PortalBuilderToolWriteResponse" "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: "A ferramenta recusou o passo (`BUILDER_OPERATION_REJECTED`): tipo de bloco inexistente, props que não passam no esquema do bloco, caminho em uso, entidade desconhecida… A mensagem diz o motivo e nada é salvo." 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-builder-tools-move-block 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/builder/tools/remove_block: post: tags: - Construtor do Portal summary: Remover um bloco description: Removes a block (and the blocks inside it) from its page. security: - bearerAuth: [] requestBody: content: application/json: schema: type: object properties: block_id: type: string minLength: 1 description: Block id (get_page). revision: type: integer minimum: 0 description: "A `revision` do rascunho lida por último. Opcional: se enviada e desatualizada, responde 409 e não salva nada." required: - block_id responses: "200": description: O que a ferramenta fez, em `data`, e a nova `revision` do rascunho (a mesma de antes se nada mudou). content: application/json: schema: $ref: "#/components/schemas/PortalBuilderToolWriteResponse" "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: "A ferramenta recusou o passo (`BUILDER_OPERATION_REJECTED`): tipo de bloco inexistente, props que não passam no esquema do bloco, caminho em uso, entidade desconhecida… A mensagem diz o motivo e nada é salvo." 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-builder-tools-remove-block 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/builder/tools/duplicate_block: post: tags: - Construtor do Portal summary: Duplicar um bloco description: Copies a block (with the blocks inside it) right after itself, with new ids. security: - bearerAuth: [] requestBody: content: application/json: schema: type: object properties: block_id: type: string minLength: 1 description: Block id (get_page). revision: type: integer minimum: 0 description: "A `revision` do rascunho lida por último. Opcional: se enviada e desatualizada, responde 409 e não salva nada." required: - block_id responses: "200": description: O que a ferramenta fez, em `data`, e a nova `revision` do rascunho (a mesma de antes se nada mudou). content: application/json: schema: $ref: "#/components/schemas/PortalBuilderToolWriteResponse" "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: "A ferramenta recusou o passo (`BUILDER_OPERATION_REJECTED`): tipo de bloco inexistente, props que não passam no esquema do bloco, caminho em uso, entidade desconhecida… A mensagem diz o motivo e nada é salvo." 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-builder-tools-duplicate-block 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/builder/tools/register_entity: post: tags: - Construtor do Portal summary: Registrar uma entidade a partir de uma fonte de dados description: "Registers an entity (data blocks bind to it) from an operation of a connected data source (describe_data_source), with the fields inferred from a sample of its records, and starts its first sync. Use it when the operator wants data that no entity has yet. It takes effect in the workspace right away (it is not part of the draft); the new entity can be used by blocks in this same answer. The workspace caps how many fields a new entity keeps: when the source has more, the refusal lists every field with a sample value — call again with `fields` set to the ones the portal needs (what it shows, filters or sums, and whatever identifies the customer the record belongs to)." security: - bearerAuth: [] requestBody: content: application/json: schema: type: object properties: data_source_id: type: string format: uuid operation_key: type: string minLength: 1 description: Operation key (describe_data_source); prefer a "list" operation. params: type: object additionalProperties: {} default: {} description: Fixed parameters the operation needs, if any. key: type: string pattern: ^[a-z][a-z0-9_]{0,62}$ description: Entity key; omitted = inferred from the operation. name: type: string minLength: 1 maxLength: 200 description: Singular name in Portuguese, e.g. "Contrato". name_plural: type: string minLength: 1 maxLength: 200 description: Plural name, e.g. "Contratos". fields: type: array items: type: string minLength: 1 minItems: 1 description: Field keys to keep, from the list a refusal gives; omitted = every visible field the sample shows. field_names: type: object additionalProperties: type: string minLength: 1 maxLength: 200 description: 'Labels in Brazilian Portuguese for the kept fields, by key ({ "amount": "Valor", "expire_at": "Vencimento" }): they are the column headers the customers read.' owner_field: type: string minLength: 1 description: The field saying which customer the record belongs to (the titular), when the inferred one is wrong or missing. On a CUSTOMERS entity it is its own id (each customer owns their own record); on a data entity, the customer id it carries (e.g. customer_id). When the portal is keyed by CPF/CNPJ, the document field instead. owner_match: type: string enum: - external_id - document_number description: "How the owner is compared to the users' tenant ID: external_id = as text (an id); document_number = as a CPF/CNPJ, digits only on both sides, so \"32.013.964/0001-60\" matches \"32013964000160\". Use document_number whenever the owner field holds a CPF/CNPJ." required: - data_source_id - operation_key responses: "200": description: O que a ferramenta fez, em `data`, e a nova `revision` do rascunho (a mesma de antes se nada mudou). content: application/json: schema: $ref: "#/components/schemas/PortalBuilderToolWriteResponse" "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: "A ferramenta recusou o passo (`BUILDER_OPERATION_REJECTED`): tipo de bloco inexistente, props que não passam no esquema do bloco, caminho em uso, entidade desconhecida… A mensagem diz o motivo e nada é salvo." 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-builder-tools-register-entity 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/builder/tools/rename_entity_fields: post: tags: - Construtor do Portal summary: Renomear os campos de uma entidade description: 'Changes an existing entity: renames its fields — the labels the blocks show (table headers, card labels) — and, optionally, the entity itself, and can set its owner field (the titular: whose record it is). Use it when the labels came from the source in English or as raw keys ("Expire at", "customer_cnpj_cpf"): customers read them, so they go in Brazilian Portuguese; and when the owner is wrong or missing (a customers entity owns its records by its own id). Keys stay; a new owner maps the stored records again. It takes effect in the workspace right away, not in the draft.' security: - bearerAuth: [] requestBody: content: application/json: schema: type: object properties: entity: type: string minLength: 1 description: Entity key (list_entities). names: type: object additionalProperties: type: string minLength: 1 maxLength: 200 default: {} description: 'New label by field key, e.g. { "amount": "Valor", "expire_at": "Vencimento" }.' name: type: string minLength: 1 maxLength: 200 description: New singular name of the entity. name_plural: type: string minLength: 1 maxLength: 200 description: New plural name of the entity. owner_field: type: string minLength: 1 description: New owner field (a field key of the entity, a computed one included). owner_match: type: string enum: - external_id - document_number description: "How the owner is compared to the users' tenant ID: external_id = as text (an id); document_number = as a CPF/CNPJ, digits only on both sides, so \"32.013.964/0001-60\" matches \"32013964000160\". Use document_number whenever the owner field holds a CPF/CNPJ." required: - entity responses: "200": description: O que a ferramenta fez, em `data`, e a nova `revision` do rascunho (a mesma de antes se nada mudou). content: application/json: schema: $ref: "#/components/schemas/PortalBuilderToolWriteResponse" "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: "A ferramenta recusou o passo (`BUILDER_OPERATION_REJECTED`): tipo de bloco inexistente, props que não passam no esquema do bloco, caminho em uso, entidade desconhecida… A mensagem diz o motivo e nada é salvo." 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-builder-tools-rename-entity-fields 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/builder/tools/save_computed_field: post: tags: - Construtor do Portal summary: Salvar um campo calculado description: "Adds a computed field to an entity — a value derived from the other fields by an expression (n8n style) — or changes the expression of a computed field it already has (same key). Use it when the operator wants a value the source does not give as is: part of a text, a join of fields, a formatted date or amount, a label from a condition. It is tried on stored records first (an expression that fails on all of them is refused, nothing saved), then saved to the entity in the workspace right away (not part of the draft) and computed on every stored record from the data it already has (no new fetch from the source). Blocks and sample_records see it in this same answer." security: - bearerAuth: [] requestBody: content: application/json: schema: type: object properties: entity: type: string minLength: 1 description: Entity key (list_entities). key: type: string pattern: ^[a-z][a-z0-9_]{0,62}$ description: Field key, snake_case. Must not be a field the source maps. name: type: string minLength: 1 maxLength: 200 description: Field label in Portuguese, e.g. "Descrição curta". expression: type: string minLength: 1 maxLength: 4000 description: Template with {{ }}, e.g. "{{ $resource.description.split('\\r\\n')[0] }}". data_type: type: string enum: - string - int - decimal - money - bool - date - datetime - email - enum - document - phone - url - file - array - json default: string description: "What the expression gives: string, int, decimal, money, bool, date, datetime…" required: - entity - key - name - expression responses: "200": description: O que a ferramenta fez, em `data`, e a nova `revision` do rascunho (a mesma de antes se nada mudou). content: application/json: schema: $ref: "#/components/schemas/PortalBuilderToolWriteResponse" "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: "A ferramenta recusou o passo (`BUILDER_OPERATION_REJECTED`): tipo de bloco inexistente, props que não passam no esquema do bloco, caminho em uso, entidade desconhecida… A mensagem diz o motivo e nada é salvo." 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-builder-tools-save-computed-field 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/builder/versions/{number}/restore: post: tags: - Construtor do Portal summary: Restaurar uma versão no rascunho description: "Copia uma versão publicada para o rascunho, substituindo as páginas dele — para continuar editando a partir de uma versão antiga. Nada vai ao ar: o portal só muda quando o rascunho for publicado. (Colocar uma versão antiga no ar é `.../rollback`.) `revision` é opcional: enviada e desatualizada, responde 409." 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 requestBody: content: application/json: schema: type: object properties: revision: type: integer minimum: 0 description: "A `revision` do rascunho lida por último. Opcional: se enviada e desatualizada, responde 409 e não salva nada." responses: "200": description: "Rascunho com as páginas da versão: nova `revision`, número restaurado e quantas páginas." content: application/json: schema: $ref: "#/components/schemas/PortalBuilderRestoreResponse" "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: post-builder-versions-number-restore /v1/builder/theme: patch: tags: - Construtor do Portal summary: Alterar as cores do tema do portal description: Altera cores do tema das páginas do portal (a aba Visual do construtor) no rascunho, por modo, em hex. Só as cores enviadas mudam; o portal no ar muda quando o rascunho for publicado. Para ler as cores atuais e o que cada uma faz, use `GET /builder/tools/get_theme`. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PortalBuilderThemeRequest" responses: "200": description: "Tema do rascunho: nova `revision`, se o tema mudou e quantas cores foram enviadas." content: application/json: schema: $ref: "#/components/schemas/PortalBuilderThemeResponse" "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-builder-theme 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. Quando a `url` muda de origem, caminho ou query string (a ordem dos parâmetros não conta) e `auth_type` não vem na mesma requisição, as credenciais guardadas são descartadas (`auth_type` passa a `none`): elas foram dadas para o destino anterior. O segredo de assinatura é mantido — use `rotate_secret` se o endpoint mudou de dono." 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 (POST /imports) 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: Só os arquivos deste tenant. required: false name: tenant_id in: query - schema: type: string format: uuid description: Só os arquivos deste tipo. required: false name: type_id in: query - schema: type: string description: Só os arquivos com esta tag. required: false name: tag 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 /v1/asset_types: get: tags: - Tipos de arquivo summary: Listar tipos de arquivo description: Os tipos de arquivo do workspace, por nome. Um bloco Arquivos do Usuário do portal lista os arquivos dos tipos que escolhe. security: - bearerAuth: [] responses: "200": description: Os tipos de arquivo. content: application/json: schema: $ref: "#/components/schemas/AssetTypeListResponse" "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-asset-types 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: - Tipos de arquivo summary: Criar tipo de arquivo description: Cria um tipo de arquivo. Depois, use o `id` em `type_id` dos arquivos. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/AssetTypeRequest" responses: "201": description: O tipo criado. content: application/json: schema: $ref: "#/components/schemas/AssetTypeResponse" "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-asset-types 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/asset_types/{id}: get: tags: - Tipos de arquivo summary: Buscar tipo de arquivo description: Um tipo de arquivo. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID do tipo de 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 tipo de arquivo. content: application/json: schema: $ref: "#/components/schemas/AssetTypeResponse" "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-asset-types-id patch: tags: - Tipos de arquivo summary: Renomear tipo de arquivo description: Muda o nome de um tipo de arquivo. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID do tipo de 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/AssetTypeRequest" responses: "200": description: O tipo atualizado. content: application/json: schema: $ref: "#/components/schemas/AssetTypeResponse" "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-asset-types-id delete: tags: - Tipos de arquivo summary: Remover tipo de arquivo description: Remove o tipo. Os arquivos dele continuam, sem tipo — e saem dos blocos Arquivos do Usuário que listavam esse tipo. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID do tipo de 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 tipo foi 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-asset-types-id /v1/checklists: get: tags: - Checklists summary: Listar checklists description: Os blocos Lista de Tarefas do portal publicado do workspace, página por página. As tarefas são escritas no builder; o progresso é de cada tenant (`GET /checklists/{id}/progress`). security: - bearerAuth: [] responses: "200": description: As checklists. content: application/json: schema: $ref: "#/components/schemas/ChecklistListResponse" "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-checklists 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/checklists/{id}: get: tags: - Checklists summary: Ver checklist description: "Uma checklist do portal publicado: etapas e tarefas visíveis." security: - bearerAuth: [] parameters: - schema: type: string description: "ID da checklist: o id do bloco Lista de Tarefas no portal publicado (`GET /checklists`)." 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 checklist. content: application/json: schema: $ref: "#/components/schemas/ChecklistResponse" "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-checklists-id /v1/checklists/{id}/progress: get: tags: - Checklists summary: Ver progresso do tenant description: Onde um tenant está numa checklist, tarefa por tarefa, com concluídas/total por etapa. Todos os usuários do portal do mesmo tenant veem esse mesmo progresso. security: - bearerAuth: [] parameters: - schema: type: string description: "ID da checklist: o id do bloco Lista de Tarefas no portal publicado (`GET /checklists`)." required: true name: id in: path - schema: type: string description: Tenant ID dos usuários do portal donos do progresso — todos os usuários do mesmo tenant veem a mesma checklist. Informe este ou `portal_user_id`. required: false name: tenant_id in: query - schema: type: string description: "Um usuário do portal (id ou external_id): vale o progresso do tenant dele (um usuário sem tenant tem uma checklist só dele). Informe este ou `tenant_id`." required: false name: portal_user_id 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 progresso do tenant. content: application/json: schema: $ref: "#/components/schemas/ChecklistProgressResponse" "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-checklists-id-progress put: tags: - Checklists summary: Alterar progresso do tenant description: Define o status de uma ou mais tarefas para o tenant (cria o progresso no primeiro uso). Os usuários do tenant veem a mudança no portal. security: - bearerAuth: [] parameters: - schema: type: string description: "ID da checklist: o id do bloco Lista de Tarefas no portal publicado (`GET /checklists`)." 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/ChecklistProgressUpdateRequest" responses: "200": description: O progresso do tenant. content: application/json: schema: $ref: "#/components/schemas/ChecklistProgressResponse" "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-checklists-id-progress delete: tags: - Checklists summary: Reiniciar progresso do tenant description: "Volta as tarefas de `task_ids` (todas, sem ele) para pendente e esquece os arquivos enviados. É uma atualização: o histórico fica nos eventos e na auditoria." security: - bearerAuth: [] parameters: - schema: type: string description: "ID da checklist: o id do bloco Lista de Tarefas no portal publicado (`GET /checklists`)." required: true name: id in: path - schema: type: string description: Tenant ID dos usuários do portal donos do progresso — todos os usuários do mesmo tenant veem a mesma checklist. Informe este ou `portal_user_id`. required: false name: tenant_id in: query - schema: type: string description: "Um usuário do portal (id ou external_id): vale o progresso do tenant dele (um usuário sem tenant tem uma checklist só dele). Informe este ou `tenant_id`." required: false name: portal_user_id in: query - schema: type: string description: IDs das tarefas, separados por vírgula. Sem ele, todas as tarefas da checklist. required: false name: task_ids 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 progresso do tenant. content: application/json: schema: $ref: "#/components/schemas/ChecklistProgressResponse" "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-checklists-id-progress /v1/checklists/{id}/progress/file: get: tags: - Checklists summary: Baixar arquivo da tarefa description: O arquivo que o tenant enviou para uma tarefa do tipo Solicitação. security: - bearerAuth: [] parameters: - schema: type: string description: "ID da checklist: o id do bloco Lista de Tarefas no portal publicado (`GET /checklists`)." required: true name: id in: path - schema: type: string description: Tenant ID dos usuários do portal donos do progresso — todos os usuários do mesmo tenant veem a mesma checklist. Informe este ou `portal_user_id`. required: false name: tenant_id in: query - schema: type: string description: "Um usuário do portal (id ou external_id): vale o progresso do tenant dele (um usuário sem tenant tem uma checklist só dele). Informe este ou `tenant_id`." required: false name: portal_user_id in: query - schema: type: string description: ID da tarefa. required: true name: task_id 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-checklists-id-progress-file post: tags: - Checklists summary: Enviar arquivo da tarefa description: Envia, pelo tenant, o arquivo de uma tarefa do tipo Solicitação (`content_base64`), substituindo o anterior. security: - bearerAuth: [] parameters: - schema: type: string description: "ID da checklist: o id do bloco Lista de Tarefas no portal publicado (`GET /checklists`)." 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/ChecklistFileUploadRequest" responses: "201": description: O arquivo registrado. content: application/json: schema: $ref: "#/components/schemas/ChecklistFileResponse" "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-checklists-id-progress-file delete: tags: - Checklists summary: Remover arquivo da tarefa description: Retira o arquivo que o tenant enviou para uma tarefa. security: - bearerAuth: [] parameters: - schema: type: string description: "ID da checklist: o id do bloco Lista de Tarefas no portal publicado (`GET /checklists`)." required: true name: id in: path - schema: type: string description: Tenant ID dos usuários do portal donos do progresso — todos os usuários do mesmo tenant veem a mesma checklist. Informe este ou `portal_user_id`. required: false name: tenant_id in: query - schema: type: string description: "Um usuário do portal (id ou external_id): vale o progresso do tenant dele (um usuário sem tenant tem uma checklist só dele). Informe este ou `tenant_id`." required: false name: portal_user_id in: query - schema: type: string description: ID da tarefa. required: true name: task_id 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: Remover arquivo da tarefa 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-checklists-id-progress-file /v1/comments: get: tags: - Comentários summary: Listar comentários description: Os comentários da conversa de um tenant (`tenant_id` ou `portal_user_id`) ou, sem nenhum dos dois, de todas as conversas do workspace. Mais recentes primeiro, paginado. 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: Tenant ID dos usuários do portal donos da conversa — todos os usuários do mesmo tenant veem os mesmos comentários. Informe este ou `portal_user_id`. required: false name: tenant_id in: query - schema: type: string description: "Um usuário do portal (id ou external_id): vale a conversa do tenant dele (um usuário sem tenant tem uma conversa só dele). Informe este ou `tenant_id`." required: false name: portal_user_id in: query - schema: type: string enum: - "true" - "false" description: "`true` = só notas internas; `false` = só o que o portal mostra." required: false name: internal in: query - schema: type: string enum: - portal_user - member - api description: Só comentários escritos por `portal_user` (usuário do portal), `member` (membro da equipe) ou `api`. required: false name: author_type 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: Comentários. content: application/json: schema: $ref: "#/components/schemas/CommentListResponse" "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-comments post: tags: - Comentários summary: Criar comentário description: Adiciona um comentário à conversa de um tenant, em nome da equipe. Todos os usuários do portal desse tenant veem a mensagem no bloco Comentários — a menos que `internal` seja `true`. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/CommentCreateRequest" responses: "201": description: Comentário criado. content: application/json: schema: $ref: "#/components/schemas/CommentResponse" "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-comments 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/comments/{id}: get: tags: - Comentários summary: Buscar comentário description: Um comentário. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID do comentário. 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 comentário. content: application/json: schema: $ref: "#/components/schemas/CommentResponse" "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-comments-id delete: tags: - Comentários summary: Excluir comentário description: "Tira o comentário da conversa (exclusão lógica): ele some do portal e do dashboard para todos." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: ID do comentário. 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: Comentário 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-comments-id webhooks: {}