openapi: 3.1.0 info: title: API do Dashboard Mágico version: 1.0.0 description: |- Hey dev, have fun! ✨ > **Documentation index** — fetch the full index at [https://docs.dashboards.kobana.com.br/llms.txt](https://docs.dashboards.kobana.com.br/llms.txt). Use this file to discover every available page before exploring further. > **Mind the API versions** — you are reading the **v1.0** documentation of the Magic Dashboard API, which covers the organization, its portal users and the dashboard team. Resources like **Payments, Transfers, Statements and Pix Receivables** live in other Kobana APIs — use the product picker in the top menu to switch. ## Format The API only accepts `JSON`. Every request must use `Content-Type: application/json`. All responses use `snake_case`. | Field type | Format | | :--- | :--- | | **DateTime** | [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) format. Examples — Date: `2026-01-24`. Date and time: `2026-01-24T10:07Z` | | **UUID** | Resource identifiers as UUID v4 | ## Conventions Conventions used in this documentation: | Convention | Description | | :--- | :--- | | **`:variable`** | A variable name that must be replaced in the URL. | | **`#{variable}`** | A variable name that must be replaced with values from your account. | | **`...`** | Response content truncated for readability. | | **`$KOBANA_TOKEN`** | Access token. For command-line testing, export it: `export KOBANA_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxx` then paste the docs commands into your terminal. | ## Return Codes The API returns standard HTTP status codes: | | Code | Description | | :--- | :--- | :--- | | ✅ | **200 OK** | Successful request with a response body. | | ✅ | **201 Created** | Resource created successfully. | | ✅ | **204 No Content** | Successful request without a response body. | | ❌ | **400 Bad Request** | Invalid request, usually malformed content. | | ❌ | **401 Unauthorized** | Missing or invalid access token. | | ❌ | **403 Forbidden** | API access blocked or user not authorized. | | ❌ | **404 Not Found** | Resource not found. | | ❌ | **422 Unprocessable Entity** | Valid request, but the data is not. | | ❌ | **429 Too Many Requests** | Rate limit reached. | | ❌ | **500 Internal Server Error** | Internal processing error. Check [server status](https://status.kobana.com.br). | ## Request ID Every request has an associated identifier in the `Request-Id` response header. This value helps with debugging and auditing — requests and their IDs are available in the system dashboard. Request logs are retained for **30 days**. When opening a support ticket about a specific request, provide the `Request-Id` to speed up the investigation. ## Security The Kobana API uses **2048-bit SSL** certificates. Every request must use **HTTPS** — calls on port 80 are redirected to 443. Clients must support `TLSv1.2` or `TLSv1.3` with one of the ciphers: `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` and `TLSv1.1` are not supported. ## HTTP Caching Use HTTP cache headers to reduce load and improve speed. Most responses include `ETag` and/or `Last-Modified` — store these values and send them back on follow-up requests via `If-None-Match` and `If-Modified-Since`. If the resource hasn't changed you'll get `304 Not Modified` — no body, no reprocessing. More info: [HTTP Cache Docs](http://www.mnot.net/cache_docs/). ## Error Handling 5xx errors mean a server failure: **500 Internal Server Error** (application unavailable), **502 Bad Gateway**, **503 Service Unavailable** and **504 Gateway Timeout** (point-in-time infrastructure failures). Your application must catch these and retry the request after a few minutes with backoff. Server status: [https://status.kobana.com.br](https://status.kobana.com.br). license: name: Proprietário — Kobana url: https://kobana.com.br servers: - url: https://api.dashboards.kobana.com.br description: Production. Overridden at runtime when `API_V1_PUBLIC_URL` is set. - url: https://api.dashboards.sandbox.kobana.com.br description: Sandbox — isolated testing environment, separate from production. components: schemas: ApiV1Error: type: object properties: error: type: object properties: code: type: string description: Stable error code. Use this field to handle errors programmatically — never parse `message`. example: invalid_token message: type: string description: Human-readable message. Never includes user data verbatim. example: Cabeçalho Authorization ausente. details: description: "Optional error-specific payload (e.g.: `{ required, granted }` in `insufficient_scope`)." required: - code - message description: Error envelope. Present in every 4xx and 5xx response. required: - error PaginationMeta: type: object properties: total: type: integer description: Total items across all pages. page: type: integer description: Current page (starts at 1). per_page: type: integer description: Items per page. total_pages: type: integer description: Total pages. 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: Legal name or display name. nickname: type: - string - "null" legal_name: type: - string - "null" document_type: type: - string - "null" enum: - cpf - cnpj description: "Document type: `cpf` or `cnpj`." document_number: type: - string - "null" description: Document number (digits only). kind: type: - string - "null" enum: - individual - company birthday: type: - string - "null" notes: type: - string - "null" addresses: description: List of addresses. phones: description: List of contact phones. emails: description: List of contact emails. 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: Stable public identifier of the resource. external_id: type: - string - "null" description: External identifier for the organization in Kobana's system. status: type: string description: "Organization status (e.g.: `active`)." created_at: type: string format: date-time updated_at: type: string format: date-time metadata: type: - object - "null" additionalProperties: {} description: Arbitrary metadata. Internal keys (`apiKeys`, `encryptionKey`, `secrets`) are stripped before the response. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). Unlike `metadata`, it is not sanitized — do not store secrets here. person: allOf: - $ref: "#/components/schemas/OrganizationPersonV1" - description: Organization registration data (name, document, contacts, addresses). Always included. 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: Display name of the organization. email: type: string format: email description: Primary contact email of the organization. phone: type: string description: Primary contact phone of the organization. addresses: type: array items: {} description: List of organization addresses. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). MeUserV1: type: - object - "null" properties: id: type: string format: uuid description: Dashboard member identifier. name: type: - string - "null" description: Member name. email: type: string description: Member email. required: - id - name - email description: Person the token belongs to; `null` when it is not a person's token (machine token). MeOrganizationV1: type: object properties: id: type: string format: uuid description: Identifier of the organization the token belongs to. name: type: - string - "null" description: Display name of the organization. external_id: type: - string - "null" description: External identifier of the organization in Kobana's system. required: - id - name - external_id MeTokenV1: type: object properties: type: type: string enum: - oauth - api_key description: "`oauth` (authorization flow) or `api_key` (personal or machine token)." scopes: type: array items: type: string description: Scopes granted to the token. access_level: type: string enum: - read - write - all description: "Highest access level granted: `read`, `write` or `all`." expires_at: type: - string - "null" format: date-time description: Token expiry (ISO 8601), or `null` when unknown. 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: Public identifier of the Kobana account linked to the user, when there is one. email: type: string status: type: string enum: - active - pending_verification - pending_invitation - suspended - locked description: "`pending_invitation` (invitation sent), `pending_verification` (signup awaiting email confirmation), `active`, `suspended` or `locked` (locked out after failed sign-ins)." sso_only: type: boolean external_id: type: - string - "null" description: User identifier in your source system (also used by SSO). Unique per workspace. tenant_id: type: - string - "null" description: "Owner ID: the identifier the portal matches entity records against to decide what this user sees. Several users may share one `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: Read-only internal metadata generated by the system. custom_metadata: type: - object - "null" additionalProperties: {} created_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel through which the record was created (dashboard, import, api, mcp, cli, other). On API calls it comes from the `X-Request-Source` header. created_via_other: type: - string - "null" description: Name of the app that created the record when `created_via` is `other` (`X-Request-Source-Other` header). created_by_email: type: - string - "null" description: Email of the user who created the record. updated_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel of the last update to the record. updated_via_other: type: - string - "null" description: Name of the app behind the last update when `updated_via` is `other` (`X-Request-Source-Other` header). updated_by_email: type: - string - "null" description: Email of the user who made the last update. created_at: type: string format: date-time updated_at: type: string format: date-time name: type: - string - "null" description: Name of the linked contact profile, when there is one. 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: User's email (required). Unique per workspace, case-insensitive. tenant_id: type: - string - "null" description: Owner ID of the records the user will see in the portal. Send `null` to clear it. external_id: type: string description: Identifier in your external system, for idempotency/sync. sso_only: type: boolean description: When `true`, the user can only sign in through SSO. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary organization-defined metadata (key/value). required: - email PortalUserUpdateRequest: type: object properties: email: type: string description: User's email (required). Unique per workspace, case-insensitive. tenant_id: type: - string - "null" description: Owner ID of the records the user will see in the portal. Send `null` to clear it. external_id: type: - string - "null" description: Identifier in your external system, for idempotency/sync. sso_only: type: boolean description: When `true`, the user can only sign in through SSO. status: type: string enum: - active - suspended description: "Allowed transitions: `active` ↔ `suspended`." custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary organization-defined metadata (key/value). PortalUserEmailPreviewResponse: type: object properties: data: type: object properties: type: type: string enum: - invitation - verification from: type: string to: type: string subject: type: string message: type: string required: - type - from - to - subject - message required: - data PortalUserResendResponse: type: object properties: data: type: object properties: resent: type: boolean type: type: string enum: - invitation - verification required: - resent - type required: - data DashboardUserRoleSummary: type: object properties: id: type: string format: uuid description: Role UUID. name: type: string description: Role name. slug: type: string description: Role slug (stable identifier). required: - id - name - slug DashboardUserV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Stable public identifier of the resource. organization_id: type: string format: uuid description: UUID of the organization the user belongs to. person_id: type: - string - "null" format: uuid description: UUID of the person (identity record) linked to the user, when present. external_id: type: string description: External user identifier in Kobana OAuth. email: type: string format: email description: User email. name: type: - string - "null" description: Display name. picture: type: - string - "null" description: URL of the user picture. status: type: string enum: - active - pending_invitation - suspended description: "Current user status: `active`, `pending_invitation` or `suspended`." permissions: type: array items: type: string description: Ad-hoc permissions assigned directly to the user (on top of those inherited from roles). last_login_at: type: - string - "null" format: date-time description: Date/time of the last login. login_count: type: integer description: Total number of logins performed. show_getting_started: type: boolean description: Indicates whether the "Getting started" panel should be shown to the user. email_signature: type: - string - "null" description: Email signature configured by the user. metadata: type: - object - "null" additionalProperties: {} description: Internal system metadata. custom_metadata: type: - object - "null" additionalProperties: {} description: Free-form metadata defined by the client. created_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel through which the record was created (dashboard, import, api, mcp, cli, other). On API calls it comes from the `X-Request-Source` header. created_via_other: type: - string - "null" description: Name of the app that created the record when `created_via` is `other` (`X-Request-Source-Other` header). created_by_email: type: - string - "null" description: Email of the user who created the record. updated_via: type: - string - "null" enum: - dashboard - import - api - mcp - cli - other description: Channel of the last update to the record. updated_via_other: type: - string - "null" description: Name of the app behind the last update when `updated_via` is `other` (`X-Request-Source-Other` header). updated_by_email: type: - string - "null" description: Email of the user who made the last update. created_at: type: string format: date-time updated_at: type: string format: date-time roles: type: array items: $ref: "#/components/schemas/DashboardUserRoleSummary" description: Roles assigned to the user, expanded as `{ 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: Email of the user to invite. name: type: string description: User name (optional — may be filled in by the user on first login). external_id: type: string description: "External user identifier, stored as an attribute of the member. It does not define the user identity: that is always resolved by `email`." role_ids: type: array items: type: string format: uuid minItems: 1 description: List of role UUIDs (`team_roles`) to assign to the user. Must contain at least one item. permissions: type: array items: type: string description: Additional ad-hoc permissions (on top of those inherited from roles). Accepts the same permission slugs. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). required: - email - role_ids DashboardUserUpdateRequest: type: object properties: name: type: string description: New display name. picture: type: string description: URL of the user picture. status: type: string enum: - active - pending_invitation - suspended description: "New status: `active`, `pending_invitation` or `suspended`." permissions: type: array items: type: string description: Full list of ad-hoc permissions (replaces the previous list). role_ids: type: array items: type: string format: uuid description: Full list of role UUIDs (replaces the current assignments). external_id: type: string description: Identifier in your external system, for idempotency/sync. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). TeamRoleV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Stable public identifier of the resource. organization_id: type: string format: uuid description: UUID of the organization the role belongs to. name: type: string description: Role name. slug: type: string description: Stable role slug. description: type: - string - "null" description: Role description. permissions: type: array items: type: string description: Permission slugs granted by the role. is_system: type: boolean description: Indicates whether the role is system-managed (not editable/removable). is_active: type: boolean description: Indicates whether the role is active and available for assignment. display_order: type: integer description: Display order of the role in the UI. metadata: type: - object - "null" additionalProperties: {} description: Internal role metadata. external_id: type: - string - "null" description: Identifier in your external system, for idempotency/sync. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). created_at: type: string format: date-time updated_at: type: string format: date-time users_count: type: integer description: Number of users currently linked to the role. 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: Role name (shown in the UI). slug: type: string pattern: ^[a-z][a-z0-9_]*$ description: "Stable slug used to reference the role (e.g.: `support_manager`)." example: portal_manager description: type: string description: Optional description of what the role grants. permissions: type: array items: type: string description: List of permission slugs granted by the role. is_active: type: boolean description: Indicates whether the role is active and can be assigned. external_id: type: string description: Identifier in your external system, for idempotency/sync. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). required: - name - slug - permissions TeamRoleUpdateRequest: type: object properties: name: type: string minLength: 1 description: New role name. slug: type: string pattern: ^[a-z][a-z0-9_]*$ description: New role slug (same rules as on creation). description: type: string description: New description. permissions: type: array items: type: string description: Full permission list (replaces the previous one). is_active: type: boolean description: Activates or deactivates the role. external_id: type: string description: Identifier in your external system, for idempotency/sync. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). WorkspaceV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Stable public identifier of the workspace. name: type: string description: Workspace name. role: type: - string - "null" enum: - owner - member description: "Your role in the workspace: `owner` (renames, deletes and exports it) or `member`. `null` for a machine token, which acts with the organization authority rather than a grant." max_entity_fields: type: integer description: How many fields a new entity of the workspace may keep (set by 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: Workspace name, 1 to 100 characters. required: - name WorkspaceUsageResponse: type: object properties: data: type: object properties: portal_users: type: integer description: Portal users of the workspace. integrations: type: integer description: Connectors (data sources) of the workspace. webhooks: type: integer description: Webhooks of the workspace. is_empty: type: boolean description: "`true` when there is none of the items above." required: - portal_users - integrations - webhooks - is_empty required: - data WorkspaceExportFile: type: object properties: format: type: string description: "File format: `kobana-dashboards.workspace`." version: type: integer description: Version of the file format. exported_at: type: string format: date-time required: - format - version WorkspaceImportRequest: type: object properties: data: type: object additionalProperties: {} description: The exported file, as returned by the export. name: type: string maxLength: 100 description: Name of the new workspace; defaults to the one in the file. 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` (connector paused awaiting credentials), `oauth_secret_required` (OIDC provider without a secret), `portal_domain_taken`, `signup_slug_taken` or `logos_not_copied`." name: type: string description: Name of the affected connector or provider. value: type: string description: Domain or slug that was already taken. 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: "How much was created: connectors, entities, pages and OIDC providers." warnings: type: array items: $ref: "#/components/schemas/WorkspaceImportWarning" description: What has to be finished by hand. required: - data - counts - warnings WorkspaceGrantV1: type: object properties: id: type: string format: uuid description: Workspace ID. name: type: string description: Workspace name. granted: type: boolean description: "`true` when the member holds an active grant on the workspace." role: type: - string - "null" enum: - owner - member description: Member role in the workspace (`owner` or `member`); `null` without a grant. 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: The final set of workspaces the member should reach. Removed ones are paused, not deleted. 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: Group key (the resource). label: type: string description: Display name of the group. description: type: string permissions: type: array items: type: object properties: key: type: string description: Permission key, such as `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: "Provider: `OPENAPI` (API described by an OpenAPI spec), `MCP` (MCP server) or `DATABASE` (read-only database)." kind: type: string enum: - openapi - mcp - database description: "The same provider in lowercase: `openapi`, `mcp` or `database`." name: type: string status: type: string enum: - pending - active - error - disabled description: "`pending` (saved and not tested yet, or waiting for the OAuth authorization), `active`, `error` (the last test failed) or `disabled`." is_active: type: boolean config: type: object additionalProperties: {} description: "Connection settings without secrets: base URL, auth kind, spec file, MCP transport, database host… Sensitive query-string values appear masked." credentials_set: type: array items: type: string description: Names of the configured secret fields (e.g. `token`, `password`). The values are never returned. oauth_authorized: type: boolean description: "MCP server with OAuth: `true` when access tokens are already stored." last_error: type: - string - "null" description: Message of the last connection test that failed; `null` when the last one succeeded. last_tested_at: type: - string - "null" format: date-time last_synced_at: type: - string - "null" format: date-time sync_cron: type: - string - "null" description: Sync schedule (5-field cron) in the `sync_timezone` timezone; `null` to sync on demand only. sync_timezone: type: - string - "null" operations_count: type: integer description: Number of operations of the source (endpoints, tools or tables). 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: "Stable key of the operation: `operationId` (or method + path) in OpenAPI, tool name in MCP, table/collection in a database." kind: type: string enum: - list - retrieve - create - update - delete - action access: type: string enum: - read - write description: "`read` (can feed entities) or `write`." name: type: string description: type: - string - "null" method: type: - string - "null" path: type: - string - "null" external_object: type: - string - "null" description: External object the operation returns (e.g. `customer`), when identified. tags: type: array items: type: string input_schema: description: Parameters the operation accepts (JSON Schema). output_schema: description: Response shape (JSON Schema), when known. fields: description: Fields of the returned records, with path and type. records_path: type: - string - "null" description: Path, in the response, of the list of records. pagination: description: How the operation paginates (page, offset, cursor), when detected. incremental: description: Incremental read parameter (e.g. `updated_since`), when detected. enabled: type: boolean description: Disabled operations do not feed entities. 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: Operations of the source, ordered by `position`. required: - operations DataSourceConnectionTestV1: type: object properties: success: type: boolean message: type: string description: Summary of the outcome, in Portuguese, ready to display. http_status: type: integer duration_ms: type: integer operation_key: type: - string - "null" description: "OpenAPI: operation used as the probe of the test." records_found: type: - integer - "null" tools_count: type: integer description: "MCP: tools listed by the server." requires_authorization: type: boolean description: "MCP: the server requires an OAuth authorization before any call." objects_count: type: integer description: "Database: tables, views and collections found." required: - success - message DataSourceRequestLogSummaryV1: type: object properties: id: type: string format: uuid service: type: string method: type: string endpoint: type: string description: URL called (sensitive values masked) or the database query. 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 called (sensitive values masked) or the database query. 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: HTTP headers, with secrets masked. request_body: type: - string - "null" response_headers: description: HTTP headers, with secrets masked. 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: Product key, used as `product` when connecting. name: type: string description: type: string docs_url: type: string token_help: type: string description: Where to get the product's API token. base_urls: type: object additionalProperties: type: string description: Base URL per environment (`production`, `sandbox`). workspace_header: type: - string - "null" description: Header the product reads to pick a workspace inside the token's organization, when there is one. 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: Authentication the spec declares, already in the shape of the `auth` field. 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: The OpenAPI 3.x or Swagger 2.0 document as text (JSON or YAML), up to 5 MB — also bounded by the API's 2 MB body limit. spec_file_name: type: string description: File name of the spec (`openapi.yaml`). Guessed from the content when omitted. certificate: type: object properties: filename: type: string description: "Original file name: .pfx, .p12, .pem, .crt or .cer." content_base64: type: string description: The file, base64-encoded (up to 64 KB once decoded). required: - filename - content_base64 description: Client certificate for mTLS (`auth.kind = "cert"`). name: type: string description: Display name, unique per workspace and kind. Derived from the spec, the host or the database when omitted. base_url: type: string description: Base URL of the API. Defaults to the first absolute server of the 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: "How the API authenticates: `none`, `header`, `query`, `bearer`, `basic` or `cert`. For `header`/`query`, send the key names and values; a blank value on an update keeps the stored one." credentials: type: object properties: token: type: string username: type: string password: type: string certificate_password: type: string description: "Secrets of the chosen auth: `token` (bearer), `username`/`password` (basic), `certificate_password` (cert). Stored encrypted and never returned." response_format: type: string enum: - json - xml required: - spec DataSourceMcpCreateRequest: type: object properties: name: type: string description: Display name, unique per workspace and kind. Derived from the spec, the host or the database when omitted. url: type: string description: MCP server URL (Streamable HTTP or SSE endpoint). A token in the query string is stored encrypted. transport: type: string enum: - http - sse headers: anyOf: - type: string - type: object additionalProperties: type: string description: "Extra headers sent on every call: an object, or one `Name: value` per line. Stored encrypted." 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 of the MCP server: `none`, `dcr` (dynamic client registration) or `client` (your own client id/secret)." required: - url DataSourceDatabaseCreateRequest: type: object properties: engine: type: string enum: - postgres - mysql - mariadb - mssql - mongodb name: type: string description: Display name, unique per workspace and kind. Derived from the spec, the host or the database when omitted. 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: "MongoDB only: the full connection string (instead of host, port, username and password). Username/password (SCRAM) authentication only; accepted options: authSource, authMechanism (SCRAM-SHA-1/SCRAM-SHA-256), replicaSet, tls/ssl, retryWrites, retryReads, w, journal, wtimeoutMS, readPreference, readConcernLevel, appName, directConnection, loadBalanced, compressors, zlibCompressionLevel and the pool timeouts/limits (maxPoolSize, minPoolSize, maxIdleTimeMS, connectTimeoutMS, socketTimeoutMS, serverSelectionTimeoutMS, heartbeatFrequencyMS, localThresholdMS, maxStalenessSeconds). Any other option is refused with 422." ssl: type: boolean ssl_verify: type: boolean required: - engine DataSourceCatalogConnectRequest: type: object properties: product: type: string description: Kobana catalog product key (see `GET /data_sources/catalog`). environment: type: string enum: - production - sandbox token: type: string description: API token of the product. Stored encrypted. workspace_id: type: - string - "null" description: Workspace inside the product, when the token's organization has more than one. name: type: string description: Display name, unique per workspace and kind. Derived from the spec, the host or the database when omitted. required: - product DataSourceSpecRequest: type: object properties: spec: type: string description: The OpenAPI 3.x or Swagger 2.0 document as text (JSON or YAML), up to 5 MB — also bounded by the API's 2 MB body limit. spec_file_name: type: string description: File name of the spec (`openapi.yaml`). Guessed from the content when omitted. required: - spec DataSourceDraftTestRequest: anyOf: - type: object properties: kind: type: string enum: - openapi spec: type: string description: The OpenAPI 3.x or Swagger 2.0 document as text (JSON or YAML), up to 5 MB — also bounded by the API's 2 MB body limit. spec_file_name: type: string description: File name of the spec (`openapi.yaml`). Guessed from the content when omitted. certificate: type: object properties: filename: type: string description: "Original file name: .pfx, .p12, .pem, .crt or .cer." content_base64: type: string description: The file, base64-encoded (up to 64 KB once decoded). required: - filename - content_base64 description: Client certificate for mTLS (`auth.kind = "cert"`). name: type: string description: Display name, unique per workspace and kind. Derived from the spec, the host or the database when omitted. base_url: type: string description: Base URL of the API. Defaults to the first absolute server of the 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: "How the API authenticates: `none`, `header`, `query`, `bearer`, `basic` or `cert`. For `header`/`query`, send the key names and values; a blank value on an update keeps the stored one." credentials: type: object properties: token: type: string username: type: string password: type: string certificate_password: type: string description: "Secrets of the chosen auth: `token` (bearer), `username`/`password` (basic), `certificate_password` (cert). Stored encrypted and never returned." response_format: type: string enum: - json - xml required: - kind - spec - type: object properties: kind: type: string enum: - mcp name: type: string description: Display name, unique per workspace and kind. Derived from the spec, the host or the database when omitted. url: type: string description: MCP server URL (Streamable HTTP or SSE endpoint). A token in the query string is stored encrypted. transport: type: string enum: - http - sse headers: anyOf: - type: string - type: object additionalProperties: type: string description: "Extra headers sent on every call: an object, or one `Name: value` per line. Stored encrypted." 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 of the MCP server: `none`, `dcr` (dynamic client registration) or `client` (your own 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: Display name, unique per workspace and kind. Derived from the spec, the host or the database when omitted. 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: "MongoDB only: the full connection string (instead of host, port, username and password). Username/password (SCRAM) authentication only; accepted options: authSource, authMechanism (SCRAM-SHA-1/SCRAM-SHA-256), replicaSet, tls/ssl, retryWrites, retryReads, w, journal, wtimeoutMS, readPreference, readConcernLevel, appName, directConnection, loadBalanced, compressors, zlibCompressionLevel and the pool timeouts/limits (maxPoolSize, minPoolSize, maxIdleTimeMS, connectTimeoutMS, socketTimeoutMS, serverSelectionTimeoutMS, heartbeatFrequencyMS, localThresholdMS, maxStalenessSeconds). Any other option is refused with 422." ssl: type: boolean ssl_verify: type: boolean required: - kind - engine - type: object properties: kind: type: string enum: - catalog product: type: string description: Kobana catalog product key (see `GET /data_sources/catalog`). environment: type: string enum: - production - sandbox token: type: string description: API token of the product. Stored encrypted. workspace_id: type: - string - "null" description: Workspace inside the product, when the token's organization has more than one. name: type: string description: Display name, unique per workspace and kind. Derived from the spec, the host or the database when omitted. required: - kind - product description: Send `kind` and the body of the matching create route. Nothing is saved. DataSourceUpdateRequest: type: object properties: name: type: string description: Display name, unique per workspace and kind. Derived from the spec, the host or the database when omitted. is_active: type: boolean base_url: type: string description: Base URL of the API. Defaults to the first absolute server of the 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: "How the API authenticates: `none`, `header`, `query`, `bearer`, `basic` or `cert`. For `header`/`query`, send the key names and values; a blank value on an update keeps the stored one." credentials: type: object properties: token: type: string username: type: string password: type: string certificate_password: type: string description: "Secrets of the chosen auth: `token` (bearer), `username`/`password` (basic), `certificate_password` (cert). Stored encrypted and never returned." certificate: type: object properties: filename: type: string description: "Original file name: .pfx, .p12, .pem, .crt or .cer." content_base64: type: string description: The file, base64-encoded (up to 64 KB once decoded). required: - filename - content_base64 description: Client certificate for mTLS (`auth.kind = "cert"`). probe_operation_key: type: - string - "null" description: "OpenAPI: operation used as the probe of the connection test; `null` picks one automatically." default_params: type: object additionalProperties: type: string description: "OpenAPI: default parameter values sent on every call." response_format: type: string enum: - json - xml url: type: string description: MCP server URL (Streamable HTTP or SSE endpoint). A token in the query string is stored encrypted. transport: type: string enum: - http - sse headers: anyOf: - type: string - type: object additionalProperties: type: string description: "Extra headers sent on every call: an object, or one `Name: value` per line. Stored encrypted." 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 of the MCP server: `none`, `dcr` (dynamic client registration) or `client` (your own 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: "MongoDB only: the full connection string (instead of host, port, username and password). Username/password (SCRAM) authentication only; accepted options: authSource, authMechanism (SCRAM-SHA-1/SCRAM-SHA-256), replicaSet, tls/ssl, retryWrites, retryReads, w, journal, wtimeoutMS, readPreference, readConcernLevel, appName, directConnection, loadBalanced, compressors, zlibCompressionLevel and the pool timeouts/limits (maxPoolSize, minPoolSize, maxIdleTimeMS, connectTimeoutMS, socketTimeoutMS, serverSelectionTimeoutMS, heartbeatFrequencyMS, localThresholdMS, maxStalenessSeconds). Any other option is refused with 422." ssl: type: boolean ssl_verify: type: boolean description: Fields accepted according to the kind of the source (OpenAPI, MCP or database); fields of another kind are ignored. Blank secret fields keep the stored ones. DataSourceScheduleRequest: type: object properties: cron: type: - string - "null" description: 5-field cron (at most every 5 minutes), or `null` to sync on demand only. timezone: type: - string - "null" description: "IANA timezone of the schedule. Default: the source's current one, or America/Sao_Paulo." required: - cron DataSourceSyncRequest: type: object properties: full: type: boolean description: "`true` re-reads everything instead of only what changed since the last sync." DataSourceOperationUpdateRequest: type: object properties: enabled: type: boolean description: Disabled operations do not feed entities. 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: The MCP server's OAuth authorization page. A person signed in to the dashboard must open it in a browser to finish the connection; `null` when there is nothing to authorize. 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: operations the spec would import." 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 of the sync run. 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: Next five runs (UTC); empty when on demand only. 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: The MCP server's OAuth authorization page. A person signed in to the dashboard must open it in a browser to finish the connection; `null` when there is nothing to authorize. 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: Pagination style; the other fields depend on it. 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: Records per page asked of the source; absent = the sync default. required: - style description: "How the sync pages through the source: `none`, `page` (`page_param`, `size_param`), `offset` (`offset_param`, `limit_param`) or `cursor` (`cursor_param`, `size_param`, `next_cursor_path`)." EntitySyncFilterV1: type: object properties: target: type: string description: Operation parameter (or table column) the filter is sent to. op: type: string enum: - eq - neq - gt - gte - lt - lte - contains - starts_with - in - is_null - not_null value: description: 'Filter value: text, number, boolean, list, `null` or a relative date `{ "relative_days": -30 }`.' required: - target - op EntityJoinSpecV1: type: object properties: base_entity_id: type: string format: uuid description: "Base entity: every one of its records enters the relation." related_entity_id: type: string format: uuid description: Related entity, matched with the base on the given fields. base_field: type: string description: Key of the base entity field used to match. related_field: type: string description: Key of the related entity field used to match. type: type: string enum: - inner - left description: "`left` (default) keeps base records without a match; `inner` only the matching ones." match: type: string enum: - exact - digits description: "`exact` (default) compares the text; `digits` compares only the digits (a CPF with and without punctuation match)." 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: "Role of the field: identifier, reference, label, amount, status, date…" source_path: type: string description: Path of the value in the source record; empty on a computed field. expression: type: - string - "null" description: "Computed field: a template over the other fields, such as `P-{{ $resource.numero }}`; `null` on a field read from the source." format: type: - string - "null" enum_options: type: - array - "null" items: {} visible: type: boolean filterable: type: boolean sortable: type: boolean position: type: integer required: - id - key - name - data_type - semantic_role - source_path - expression - format - enum_options - visible - filterable - sortable - position EntitySourceV1: type: object properties: integration_id: type: string format: uuid description: Data source (connector) the entity reads from. integration_name: type: string kind: type: string enum: - openapi - mcp - database description: "Kind of data source: `openapi`, `mcp` or `database`." source_kind: type: string enum: - operation - sql - join description: "`operation` (endpoint, tool or table), `sql` (a query on a SQL database) or `join` (a relation between two entities)." join: allOf: - $ref: "#/components/schemas/EntityJoinSpecV1" - type: - object - "null" description: "On a `join` entity: the two entities, the fields they match on and how; `null` otherwise." 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: Parameters the operation is called with. records_path: type: - string - "null" pagination: allOf: - $ref: "#/components/schemas/EntityPaginationV1" - type: - object - "null" description: Pagination of the sync; `null` = the one detected on the operation (`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: Machine name the portal blocks use; unique in the workspace (up to 63 characters). 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: "When the sync runs: `scheduled`, `manual` or `on_access` (each tenant's records are read when one of its users opens the portal)." freshness_seconds: type: integer description: "`on_access`: how many seconds a tenant's synced records count as fresh." identifier_field_key: type: - string - "null" label_field_key: type: - string - "null" owner_field_key: type: - string - "null" description: Field holding the owner ID, matched against the portal user's `tenant_id`. Without it the entity cannot be shown in the portal. owner_match: type: string enum: - external_id - document_number description: "How the owner field is compared with the `tenant_id`: as text (`external_id`) or as a CPF/CNPJ (`document_number`, digits only)." fields: type: array items: $ref: "#/components/schemas/EntityFieldV1" sampled_at: type: - string - "null" format: date-time sample: type: array items: type: object additionalProperties: {} description: A few records as the source returned them, kept to re-infer fields. 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: Where the copy of the records stands; `null` before the first sync. 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: Value of the identifier field, or a hash of the record when the entity has none. owner_id: type: - string - "null" description: Value of the owner field, matched against the portal users' `tenant_id`. data: type: object additionalProperties: {} description: The record's values by field key — what blocks, filters and sorts read. raw: type: object additionalProperties: {} description: The record as the source returned it. 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: "With `preview_as` on an `on_access` entity: where that tenant's sync stands." EntityRecordsQueryResponse: type: object properties: data: type: object properties: records: type: array items: type: object additionalProperties: {} description: "Each record's values by field key, plus `_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: How many records were removed. required: - cleared required: - data EntityAggregateResponse: type: object properties: data: type: object properties: value: anyOf: - type: number - type: string - type: "null" description: Result of the aggregate, without `group_by`. groups: type: array items: type: object properties: key: {} value: anyOf: - type: number - type: string - type: "null" required: - value description: "With `group_by`: one result per value of the field (up to 100 groups)." 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: Types of the page blocks reading the entity, one per block. 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: How many fields the workspace lets the new entity keep. records: type: array items: type: object additionalProperties: {} description: The sample of records the source returned. 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: "The entity proposed from the sample: key, names, fields and special fields." 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: "Match counts: base records, matched, unmatched." sample: type: array items: type: object additionalProperties: {} description: "The first combined rows: `{ _id, base: {...}, related: {...} | null }`." required: - base - related - stats - sample required: - data EntitySyncQueuedResponse: type: object properties: data: type: object properties: sync_id: type: string format: uuid description: ID of the queued sync. required: - sync_id required: - data EntitySyncStateResponse: type: object properties: data: type: - object - "null" properties: status: type: - string - "null" description: Status of the last sync (`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: Where the sync of the entity stands; `null` before the first one. 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: "Portal users carrying this tenant ID: how many and the first 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: "One call of the sync, whole: what was sent and what came back (secrets masked when recorded)." 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: Path of the value in the source record; empty on a computed field. expression: type: - string - "null" maxLength: 4000 description: "Computed field: a template over the other fields, such as `P-{{ $resource.numero }}`; `null` on a field read from the source." format: type: - string - "null" maxLength: 100 enum_options: type: - array - "null" items: {} maxItems: 200 visible: type: boolean description: Whether the field shows in the portal blocks (default `true`). filterable: type: boolean sortable: type: boolean required: - key - name - data_type EntityPreviewRequest: type: object properties: integration_id: type: string format: uuid description: Data source (connector) to read from. operation_id: type: string format: uuid description: Read operation (endpoint, tool or table) of the source. Send this field or `sql`, not both. sql: type: string maxLength: 20000 description: SQL query on a SQL database source. Send this field or `operation_id`. params: type: object additionalProperties: {} description: Parameters the operation is called with (default `{}`). pagination: allOf: - $ref: "#/components/schemas/EntityPaginationV1" - type: - object - "null" description: Pagination of the sync; `null` = the one detected on the operation (`operation_pagination`). sync_filters: type: array items: $ref: "#/components/schemas/EntitySyncFilterV1" maxItems: 20 description: What the sync sends to narrow the records (up to 20). Ignored on a SQL query. limit: type: integer minimum: 1 maximum: 50 description: Sample size (default 10, max 50). required: - integration_id EntityCreateRequest: type: object properties: integration_id: type: string format: uuid description: Data source (connector) to read from. operation_id: type: string format: uuid description: Read operation (endpoint, tool or table) of the source. Send this field or `sql`, not both. sql: type: string maxLength: 20000 description: SQL query on a SQL database source. Send this field or `operation_id`. params: type: object additionalProperties: {} description: Parameters the operation is called with (default `{}`). pagination: allOf: - $ref: "#/components/schemas/EntityPaginationV1" - type: - object - "null" description: Pagination of the sync; `null` = the one detected on the operation (`operation_pagination`). sync_filters: type: array items: $ref: "#/components/schemas/EntitySyncFilterV1" maxItems: 20 description: What the sync sends to narrow the records (up to 20). Ignored on a SQL query. key: type: string maxLength: 63 description: Machine name the portal blocks use; unique in the workspace (up to 63 characters). 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: Field holding the owner ID, matched against the portal user's `tenant_id`. Without it the entity cannot be shown in the portal. owner_match: type: string enum: - external_id - document_number description: "How the owner field is compared with the `tenant_id`: as text (`external_id`) or as a CPF/CNPJ (`document_number`, digits only)." sync_mode: type: string enum: - scheduled - manual - on_access description: "When the sync runs; absent: `scheduled` on create, kept on update." freshness_seconds: type: integer minimum: 60 maximum: 604800 description: "`on_access`: how many seconds a tenant's synced records count as fresh." fields: type: array items: $ref: "#/components/schemas/EntityFieldInputV1" minItems: 1 maxItems: 200 description: The fields the entity keeps, in order. On update, the whole list (matched by `key`). records_path: type: - string - "null" maxLength: 500 description: Path to the record list inside the response, when not detected. sample: type: array items: type: object additionalProperties: {} maxItems: 50 description: The preview records, kept to re-infer fields later. required: - integration_id - key - name - name_plural - fields EntityUpdateRequest: type: object properties: key: type: string maxLength: 63 description: Machine name the portal blocks use; unique in the workspace (up to 63 characters). 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: Field holding the owner ID, matched against the portal user's `tenant_id`. Without it the entity cannot be shown in the portal. owner_match: type: string enum: - external_id - document_number description: "How the owner field is compared with the `tenant_id`: as text (`external_id`) or as a CPF/CNPJ (`document_number`, digits only)." sync_mode: type: string enum: - scheduled - manual - on_access description: "When the sync runs; absent: `scheduled` on create, kept on update." freshness_seconds: type: integer minimum: 60 maximum: 604800 description: "`on_access`: how many seconds a tenant's synced records count as fresh." fields: type: array items: $ref: "#/components/schemas/EntityFieldInputV1" minItems: 1 maxItems: 200 description: The fields the entity keeps, in order. On update, the whole list (matched by `key`). pagination: allOf: - $ref: "#/components/schemas/EntityPaginationV1" - type: - object - "null" description: Pagination of the sync; `null` = the one detected on the operation (`operation_pagination`). sync_filters: type: array items: $ref: "#/components/schemas/EntitySyncFilterV1" maxItems: 20 description: Sync filters (up to 20); absent keeps the current ones. required: - key - name - name_plural - fields EntityJoinRequest: type: object properties: key: type: string maxLength: 63 description: Machine name the portal blocks use; unique in the workspace (up to 63 characters). 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: "The fields brought from each side: `{ from: base|related, field_key, key?, name? }`." label_field_key: type: - string - "null" maxLength: 63 description: Label field; absent = the copy of the base entity's label, `null` = none. owner_field_key: type: - string - "null" maxLength: 63 description: Owner field; absent = the copy of the base entity's owner, `null` = none. required: - key - name - name_plural - join - fields EntityTenantSyncRequest: type: object properties: tenant_id: type: string minLength: 1 maxLength: 500 description: Tenant ID (owner ID) to sync. In the body because it may hold any character. full: type: boolean description: When `true`, re-reads every record of the tenant. 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: File name of the uploaded og:image. og_image_url: type: string description: Public URL of the og:image — what link previews fetch (`POST /portal_builder/og_image`). og_image_meta: type: string description: Meta tags and Open Graph of the page; empty fields fall back to the SEO defaults. PortalBuilderThemeV1: type: object properties: light: type: object additionalProperties: type: string description: Palette colors, by token (`background`, `primary`…). dark: type: object additionalProperties: type: string description: Palette colors, by token (`background`, `primary`…). radius: type: string description: Corner radius, in `rem` or `px`. example: 0.5rem required: - light - dark - radius description: "The portal's visual theme: light and dark palettes and corner radius." 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: File name of the uploaded og:image. og_image_url: type: string description: Public URL of the og:image — what link previews fetch (`POST /portal_builder/og_image`). og_image_meta: type: string required: - description - keywords - robots - og_title - og_description - og_image - og_image_url - og_image_meta description: Meta tags and Open Graph every page falls back to. PortalBuilderPageV1: type: object properties: id: type: string description: Stable page id. name: type: string description: Page name in the builder and in the portal menu. path: type: string description: Path of the page in the portal URL. example: / title: type: string description: Browser-tab title. seo: $ref: "#/components/schemas/PortalBuilderPageSeoV1" show_in_menu: type: boolean description: Listed in the portal header menu. Default `true`. content: type: object additionalProperties: {} description: "Block tree of the page (Puck data). Opaque to the API: stored and returned as sent." badge: type: string enum: - "" - nova - alterada description: "Against the live version: `nova` (new), `alterada` (changed) or empty (same)." required: - id - name - path - title - seo - content - badge PortalVersionPageV1: type: object properties: id: type: string description: Stable page id. name: type: string description: Page name in the builder and in the portal menu. path: type: string description: Path of the page in the portal URL. example: / title: type: string description: Browser-tab title. seo: $ref: "#/components/schemas/PortalBuilderPageSeoV1" show_in_menu: type: boolean description: Listed in the portal header menu. Default `true`. content: type: object additionalProperties: {} description: "Block tree of the page (Puck data). Opaque to the API: stored and returned as sent." required: - id - name - path - title - seo - content PortalVersionV1: type: object properties: id: type: string format: uuid number: type: - integer - "null" description: Sequential version number (v1, v2…). status: type: string enum: - draft - published - archived description: "`published` (live), `archived` (superseded) or `draft`." note: type: - string - "null" description: Note given when publishing. summary: type: - string - "null" description: "What the version changed: the note, or the change log." 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: The portal's public host (active custom domain, or the default). required: - company_name - title - subtitle - public_host description: Portal identity (Portal settings). draft: type: - object - "null" properties: revision: type: integer description: "Optimistic lock of the draft: send it with the next save or publish." dirty: type: boolean description: "`true` when the draft differs from the live version." pages: type: array items: $ref: "#/components/schemas/PortalBuilderPageV1" editor_state: type: object additionalProperties: {} description: State the builder keeps beside the pages (change log, connections). Send back what you read. required: - revision - dirty - pages - editor_state description: The draft; `null` before the first edit. live_version: type: integer description: Number of the live version; `0` when nothing was published. 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: Stable page id (letters, digits, `_` and `-`; up to 100). Unique in the draft. name: type: string description: Page name in the builder and in the portal menu. path: type: string description: Path of the page in the portal URL. title: type: string description: Browser-tab title. seo: $ref: "#/components/schemas/PortalBuilderPageSeoV1" show_in_menu: type: boolean description: Listed in the portal header menu. Default `true`. content: type: object additionalProperties: {} description: "Block tree of the page (Puck data). Opaque to the API: stored and returned as sent." required: - id - name - path PortalBuilderDraftRequest: type: object properties: revision: type: integer minimum: 0 description: The draft `revision` you last read (`0` when there is no draft yet). pages: type: array items: $ref: "#/components/schemas/PortalBuilderPageInput" maxItems: 200 description: Every page of the draft, in menu order (up to 200). Pages left out are removed from the draft. editor_state: type: object additionalProperties: {} description: Editor state; send back what you read. Omitted = `{}`. theme: allOf: - $ref: "#/components/schemas/PortalBuilderThemeV1" - description: New theme. Omitted = keep the current one. seo_defaults: allOf: - $ref: "#/components/schemas/PortalBuilderSeoDefaultsV1" - description: New SEO defaults. Omitted = keep the current ones. required: - revision - pages PortalBuilderPublishRequest: type: object properties: revision: type: integer minimum: 0 description: The draft `revision` you last read (`0` when there is no draft yet). pages: type: array items: $ref: "#/components/schemas/PortalBuilderPageInput" maxItems: 200 description: Every page of the draft, in menu order (up to 200). Pages left out are removed from the draft. editor_state: type: object additionalProperties: {} description: Editor state; send back what you read. Omitted = `{}`. theme: allOf: - $ref: "#/components/schemas/PortalBuilderThemeV1" - description: New theme. Omitted = keep the current one. seo_defaults: allOf: - $ref: "#/components/schemas/PortalBuilderSeoDefaultsV1" - description: New SEO defaults. Omitted = keep the current ones. note: type: string maxLength: 2000 description: What changed, shown in the version history. required: - revision - pages PortalBuilderDraftSaveResponse: type: object properties: data: type: object properties: revision: type: integer description: "Optimistic lock of the draft: send it with the next save or publish." dirty: type: boolean description: "`true` when the draft differs from the live version." badges: type: object additionalProperties: type: string enum: - "" - nova - alterada description: "Badge of each page by id: `nova` (new), `alterada` (changed) or empty." required: - revision - dirty - badges required: - data PortalBuilderPublishResponse: type: object properties: data: type: object properties: revision: type: integer description: "Optimistic lock of the draft: send it with the next save or publish." 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: The plaintext to seal. Never echoed back. url: type: string minLength: 1 maxLength: 2000 description: "The webhook URL the value is for (required): the secret opens only for a request to the same origin (scheme, host and port). The host must be fixed — no `{{variables}}`." example: https://hooks.example.com/in required: - value - url PortalBuilderSecretResponse: type: object properties: data: type: object properties: value: type: string description: Sealed value (`secret:…`) to store in the block. example: secret:… required: - value required: - data PortalBuilderOgImageRequest: type: object properties: filename: type: string minLength: 1 maxLength: 300 description: Original file name. example: cover.png content_type: type: string enum: - image/png - image/jpeg - image/webp content_base64: type: string description: The image bytes, base64-encoded (a `data:…;base64,` prefix is accepted). required: - filename - content_type - content_base64 PortalBuilderOgImageResponse: type: object properties: data: type: object properties: url: type: string description: Public URL of the image. content_type: type: string size: type: integer description: Image size, in bytes. required: - url - content_type - size required: - data PortalBuilderFormSubmissionRequest: type: object properties: form_id: type: string minLength: 1 maxLength: 200 description: Id of the Form block. form_title: type: string maxLength: 200 page_path: type: string maxLength: 500 description: Path of the page holding the block. Default `/`. 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: Validation regular expression of the field. One with a dangerous (ReDoS) shape answers 422. required: - label minItems: 1 maxItems: 30 action: type: object properties: type: type: string enum: - email - webhook email_to: type: string maxLength: 2000 description: E-mail recipients, comma-separated (`email` action). email_subject: type: string maxLength: 300 email_template: type: string maxLength: 20000 webhook_endpoint_id: type: string maxLength: 100 description: Id of the workspace webhook that receives the submission (`webhook` action). required: - type values: type: object additionalProperties: type: string description: Filled-in values, by field name. submitter: type: object properties: name: type: string maxLength: 200 email: type: string maxLength: 254 description: Customer the preview acts as, for `{{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 of the Action button block. label: type: string maxLength: 200 page_path: type: string maxLength: 500 description: Path of the page holding the block. Default `/`. request: type: object properties: method: type: string enum: - POST - PUT - PATCH url: type: string maxLength: 2000 description: Full webhook URL; must start with https://. headers: type: array items: type: object properties: key: type: string maxLength: 200 value: type: string maxLength: 8000 required: - key - value maxItems: 50 description: Request headers (up to 50); a value may be a `secret:` from `POST /portal_builder/secrets`. body: type: string maxLength: 100000 required: - method - url submitter: type: object properties: name: type: string maxLength: 200 email: type: string maxLength: 254 description: Customer the preview acts as, for `{{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: HTTP status the target replied with; `null` when there was no answer. 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: Theme colors, in HSL without the `hsl()` wrapper (e.g. `210 40% 98%`). Omitted keys use the default. example: primary: 222 47% 11% PortalSettingsV1: type: object properties: id: type: - string - "null" format: uuid description: Configuration id; `null` while the portal was never configured (values are the defaults). workspace_id: type: string format: uuid company_name: type: string description: Name shown on the portal. Defaults to the organization name. title: type: - string - "null" subtitle: type: - string - "null" logo_url: type: - string - "null" description: Public URL of the logo (light backgrounds). logo_light_url: type: - string - "null" description: Public URL of the logo for dark backgrounds. favicon_url: type: - string - "null" html_lang: type: string enum: - pt-BR - en-US - es-ES description: "The portal language: the `lang` attribute of the pages' `` and the language of the login screens." light_colors: $ref: "#/components/schemas/PortalColorsV1" dark_colors: $ref: "#/components/schemas/PortalColorsV1" signup_slug: type: - string - "null" description: "The portal's address on the platform: `/portal/{signup_slug}/login`." enable_login: type: boolean description: Master switch of the portal login. enable_email_login: type: boolean description: Allows signing in with e-mail and password or magic link (requires `enable_login`). allow_password_change: type: boolean sso_enabled: type: boolean description: SSO login with a JWT signed by your system. sso_public_key: type: - string - "null" description: PUBLIC key (PEM) that verifies the SSO JWT. Never send the private key. 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: Subdomain of the address `https://{portal_slug}.{portal_domain}`. Change it with `PATCH /portal_settings/domain`. portal_domain: type: - string - "null" available_domains: type: array items: type: string description: Platform domains accepted as `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: "Status of each portal notification: `ACTIVE` (sent), `INACTIVE` (silenced) or `DISABLED` (unavailable)." notification_bcc_emails: type: array items: type: object properties: label: type: string description: Identification label (display only). address: type: string format: email required: - label - address description: Blind-copy recipients of every notification e-mail. notification_sender_name: type: - string - "null" notification_sender_email: type: - string - "null" description: Sender of the notification e-mails. Only used once `notification_sender_email_status` is `active`. notification_reply_to_email: type: - string - "null" notification_sender_email_status: type: - string - "null" enum: - pending - active - failed description: "Verification of the sender on AWS SES: `pending`, `active` or `failed`; `null` when there is no custom sender." hsts_include_subdomains: type: boolean hsts_preload: type: boolean secure_frame_headers: type: boolean description: Prevents the portal from being shown inside other sites’ iframes. 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: "Trackers per provider (`google_tag_manager`, `google_analytics`, …): `{ provider: { enabled, ...ids } }`. Unknown providers and fields are dropped." chat_integrations: type: object additionalProperties: type: object additionalProperties: anyOf: - type: string - type: boolean description: Chat widgets per provider (`intercom`, `hubspot`, `zendesk`, …), same shape as `tracking_integrations`. custom_code: type: - string - "null" description: Custom JavaScript run on every portal page. 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: "The portal language: it goes in the `lang` of the pages' `` and translates the login screens." light_colors: $ref: "#/components/schemas/PortalColorsV1" dark_colors: $ref: "#/components/schemas/PortalColorsV1" signup_slug: type: - string - "null" maxLength: 50 description: Lowercase letters, digits and hyphens; unique on the platform. `null` or `""` removes it. 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: "Status of each portal notification: `ACTIVE` (sent), `INACTIVE` (silenced) or `DISABLED` (unavailable)." notification_bcc_emails: type: array items: type: object properties: label: type: string description: Identification label (display only). address: type: string format: email required: - address maxItems: 20 description: Replaces the whole list (up to 20). notification_sender_name: type: - string - "null" maxLength: 100 notification_sender_email: type: - string - "null" maxLength: 254 description: A new address starts its AWS SES verification, which e-mails it a confirmation link. `""` reverts to the platform sender. 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: Only the content of the Google verification meta tag. seo_canonical_url: type: - string - "null" maxLength: 500 tracking_integrations: type: object additionalProperties: type: object additionalProperties: anyOf: - type: string - type: boolean description: "Trackers per provider (`google_tag_manager`, `google_analytics`, …): `{ provider: { enabled, ...ids } }`. Unknown providers and fields are dropped." chat_integrations: type: object additionalProperties: type: object additionalProperties: anyOf: - type: string - type: boolean description: Chat widgets per provider (`intercom`, `hubspot`, `zendesk`, …), same shape as `tracking_integrations`. custom_code: type: - string - "null" maxLength: 100000 description: 'Partial update: only the fields sent change. `""` clears the optional texts.' PortalLogoUploadRequest: type: object properties: filename: type: string minLength: 1 maxLength: 255 example: logo.png content_type: type: string description: "`image/png`, `image/jpeg` or `image/webp`; the favicon also accepts `image/x-icon`. SVG is not accepted." example: image/png content_base64: type: string description: File content in base64 (up to 500 KB once decoded). variant: type: string enum: - logo - logo_light - favicon description: "Which image: `logo` (default), `logo_light` (logo for dark backgrounds) or `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: "Subdomain: 3 to 50 lowercase letters, digits and hyphens (no hyphen at either end). `null` to remove." example: acme domain: type: - string - "null" description: One of the platform domains (`available_domains`). `null` to remove. 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: The portal's full address, or `null` when there is none. 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: "Why it is unavailable: `invalid_format`, `reserved`, `invalid_domain` or `taken`; `null` when it is available." required: - slug - domain - available - reason required: - data PortalSenderIdentityResponse: type: object properties: data: type: object properties: status: type: - string - "null" enum: - pending - active - failed description: "Verification of the sender on AWS SES: `pending`, `active` or `failed`; `null` when there is no custom sender." verification_requested: type: boolean description: "`true` when a new verification was requested (an e-mail was sent to the sender)." 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: "Provisioning stage: `pending_verification`, `dns_verified`, `pending_certificate`, `generating_certificate`, `active`, `certificate_failed` or `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` when CloudFront issues and renews the certificate (only the routing CNAME is needed)." 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: When the ownership TXT was found; `null` until then — or after ownership was lost (`ownership_lost`). ownership_lost: type: boolean description: "`true` when the domain was proven, but the daily check stopped finding the TXT `_dashmagico-verify.{hostname}` (3 consecutive checks spanning 7 days or more): the portal stops answering on it until the TXT is published again and the domain validated." ownership_missing_since: type: - string - "null" format: date-time description: Since when the daily check has not found the ownership TXT of a proven domain (not lost yet); `null` when the last check found it. 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: "DNS records that must be published on the domain. The TXT `_dashmagico-verify.{hostname}` (`ownership_verification`) proves the domain is yours: its value is unique to this record, and nothing is provisioned or routed before it. Keep the TXT published: ownership is checked again every day, and the domain loses it if the record is missing on 3 consecutive checks spanning 7 days or more." 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: Fully qualified hostname, e.g. `portal.example.com`. 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: The TXT `_dashmagico-verify.{hostname}` carries this domain's value (or ownership was already proven). routing_ok: type: boolean description: The routing CNAME points at the platform. validation_ok: type: boolean description: The certificate-validation CNAME is correct (always `true` with a managed certificate). 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: Text of the login button; the name when empty. issuer_url: type: string description: OpenID Connect issuer URL (https in production). client_id: type: string scopes: type: string description: "Space-separated scopes. Default: `openid email profile`." email_claim: type: string description: "Token claim that carries the e-mail. Default: `email`." has_secret: type: boolean description: Whether a client secret is stored. The secret is never returned. 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: Text of the login button; the name when empty. issuer_url: type: string maxLength: 2000 format: uri description: OpenID Connect issuer URL (https in production). client_id: type: string minLength: 1 maxLength: 500 client_secret: type: string minLength: 1 maxLength: 2000 description: "Write-only: stored encrypted and never returned." scopes: type: string maxLength: 500 description: "Space-separated scopes. Default: `openid email profile`." email_claim: type: string maxLength: 100 description: "Token claim that carries the e-mail. Default: `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: Omitted or empty keeps the current secret; a value replaces it. Never returned. 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: OpenID Connect issuer URL (https in production). 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: Why it failed when `ok` is `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: Public identifier of the endpoint. url: type: string description: URL that receives the events by POST. description: type: - string - "null" description: Free-form description of the endpoint. auth_type: type: string enum: - none - basic - bearer - header description: "Authentication sent with each delivery: `none`, `basic`, `bearer` or `header`." active: type: boolean description: When `false`, the endpoint is paused and receives no deliveries. workspace_id: type: string format: uuid description: The endpoint's workspace. It receives this workspace's events and the organization-level ones. created_at: type: string format: date-time updated_at: type: string format: date-time events: type: array items: type: string description: Subscribed event types (e.g. `api_key.db.created`). metadata: type: - object - "null" additionalProperties: {} description: Read-only internal metadata. custom_metadata: type: - object - "null" additionalProperties: {} description: Free-form organization-defined metadata. delivery_count: type: integer description: Total deliveries recorded for the endpoint (list and detail). required: - id - public_id - url - description - auth_type - active - workspace_id - created_at - updated_at - events - metadata - custom_metadata description: A webhook endpoint of the workspace. The signing secret and the authentication credentials are never returned here. WebhookWithSecretV1: allOf: - $ref: "#/components/schemas/WebhookV1" - type: object properties: secret: type: string description: Signing secret (HMAC-SHA256) in plain text. Returned ONLY on creation and rotation — store it then. example: whsec_… required: - secret description: A webhook endpoint of the workspace. The signing secret and the authentication credentials are never returned here. 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: Endpoint URL (required on creation). Must be a valid URL. example: https://example.com/webhooks events: type: array items: type: string minItems: 1 description: Event types to receive. At least one. example: - api_key.db.created description: type: - string - "null" description: Free-form description. `null` clears it. auth_type: type: string enum: - none - basic - bearer - header description: Delivery authentication (default `none`). When changing it, send the matching `auth_config` too. auth_config: type: - object - "null" additionalProperties: {} description: "Credentials for `auth_type`: basic → `{ username, password }`, bearer → `{ token }`, header → `{ key, value }`. Stored encrypted and never returned." example: token: token-123 required: - url - events WebhookUpdateRequest: type: object properties: url: type: string description: Endpoint URL (required on creation). Must be a valid URL. events: type: array items: type: string minItems: 1 description: Event types to receive. At least one. description: type: - string - "null" description: Free-form description. `null` clears it. active: type: boolean description: "`false` pauses the endpoint; `true` resumes it." auth_type: type: string enum: - none - basic - bearer - header description: Delivery authentication (default `none`). When changing it, send the matching `auth_config` too. auth_config: type: - object - "null" additionalProperties: {} description: "Credentials for `auth_type`: basic → `{ username, password }`, bearer → `{ token }`, header → `{ key, value }`. Stored encrypted and never returned." example: token: token-123 WebhookTestResponse: type: object properties: data: type: object properties: success: type: boolean description: "`true` when the endpoint answered 2xx." status_code: type: - integer - "null" description: HTTP status of the response; `null` when there was no response. delivery_id: type: string format: uuid description: Delivery recorded for the attempt. error: type: - string - "null" description: Why it failed, when it did. 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: Always `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` (waiting to be sent or retried), `delivered` (2xx) or `failed`." http_status: type: - integer - "null" description: HTTP status returned by the endpoint. error: type: - string - "null" description: Why it failed, when it did. attempts: type: integer description: Number of attempts made. next_retry_at: type: - string - "null" format: date-time description: When the next automatic attempt is scheduled. delivered_at: type: - string - "null" format: date-time created_at: type: string format: date-time request_headers: type: - object - "null" additionalProperties: {} description: Headers sent (authentication and signature as `[REDACTED]`). request_body: description: JSON payload sent. response_headers: type: - object - "null" additionalProperties: {} response_body: type: - string - "null" description: Body of the endpoint response (up to 10,000 characters). event_type: type: - string - "null" description: Type of the delivered event (global list and detail). webhook_endpoint: type: object properties: id: type: string format: uuid url: type: string description: type: - string - "null" required: - id - url - description description: Summary of the target endpoint (global list and detail). 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: One attempt to deliver an event to a webhook endpoint. Authentication and signature headers are stored as `[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: Event type. example: api_key.rotated resource_type: type: string description: Type of the resource the event is about. resource_id: type: string format: uuid description: ID of the resource the event is about. workspace_id: type: - string - "null" format: uuid description: The event's workspace; `null` for organization-level events (visible from every workspace). created_at: type: string format: date-time data: description: Event payload, as sent to webhooks. metadata: type: - object - "null" additionalProperties: {} description: Event metadata. required: - id - type - resource_type - resource_id - workspace_id - created_at - metadata description: An event of the log — what webhooks are dispatched from. Read-only. 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: The entry's workspace; `null` for organization-level actions. user_id: type: - string - "null" description: Identifier of who performed the action, when known. user_email: type: - string - "null" description: E-mail of who performed the action; `null` for machine tokens. action: type: string description: Recorded action. example: webhook.created resource_type: type: string description: Type of the affected resource. 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: Recorded changes (free-form JSON). previous_values: description: Values before the action (free-form JSON). new_values: description: Values after the action (free-form JSON). metadata: type: - object - "null" additionalProperties: {} description: Extra context (e.g. `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: "An entry of the audit trail: who changed what, when and from where. Read-only." 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: Window used, in hours. since: type: string format: date-time description: Start of the window. total_count: type: integer description: Total entries in the window. action_counts: type: array items: type: object properties: action: type: string count: type: integer required: - action - count description: The 10 most frequent actions, with the count of each. recent_logs: type: array items: $ref: "#/components/schemas/AuditLogV1" description: The 20 most recent entries of the window. 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: Public identifier of the template. organization_id: type: - string - "null" format: uuid description: Organization that owns the template. `null` for a platform default, which is read-only. name: type: string description: Template name, shown to editors. 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: Notification type the template renders. Each type has at most one active template per organization. An organization creates templates of `api_key_expiring`, `account_suspended` and `account_activated` only; e-mails carrying a sign-in link or code (portal invitation, login link, verification, password reset) always use the platform content (422 `TEMPLATE_TYPE_NOT_EDITABLE`). subject: type: string description: Email subject. Accepts `{{name}}` variables. html_body: type: string description: HTML body of the email. Accepts `{{name}}` variables, whose values are escaped on render. text_body: type: - string - "null" description: Plain-text alternative body, when there is one. bcc: type: array items: type: string description: Addresses blind-copied (BCC) on every email sent with this template. variables: type: array items: type: string description: Names of the variables the template uses (documentation for editors). is_active: type: boolean description: Whether this is the active template of its type. The others are drafts. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary organization-defined metadata (key/value). 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: Template name (required on create). 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: Notification type the template renders (required). subject: type: string description: Email subject, with `{{name}}` variables (required on create). html_body: type: string description: HTML body, with `{{name}}` variables (required on create). text_body: type: - string - "null" description: Plain-text alternative body. `null` clears it. bcc: anyOf: - type: array items: type: string - type: string - type: "null" description: List (or a single address) of BCC emails. Invalid addresses return 422; omitted on update, the current list is kept. variables: type: array items: type: string description: Names of the variables the template uses. is_active: type: boolean description: Makes this the active template of its type; the previous active one becomes a draft. Defaults to `false` on create. required: - name - type - subject - html_body EmailTemplateUpdateRequest: type: object properties: name: type: string description: Template name (required on create). subject: type: string description: Email subject, with `{{name}}` variables (required on create). html_body: type: string description: HTML body, with `{{name}}` variables (required on create). text_body: type: - string - "null" description: Plain-text alternative body. `null` clears it. bcc: anyOf: - type: array items: type: string - type: string - type: "null" description: List (or a single address) of BCC emails. Invalid addresses return 422; omitted on update, the current list is kept. variables: type: array items: type: string description: Names of the variables the template uses. is_active: type: boolean description: Makes this the active template of its type; the previous active one becomes a draft. Defaults to `false` on create. public_id: type: string format: uuid description: New public identifier (UUID), when the organization allows choosing it. EmailTemplateDuplicateRequest: type: object properties: new_name: type: string description: 'Name of the copy. Default: " (Cópia)".' EmailTemplateRenderRequest: type: object properties: variables: type: object additionalProperties: {} description: Values for the template `{{name}}` variables. EmailTemplateRenderResponse: type: object properties: data: type: object properties: subject: type: string description: Rendered subject. html_body: type: string description: Rendered HTML body. text_body: type: - string - "null" description: Rendered plain-text body, when the template has one. bcc: type: array items: type: string description: Template BCC list (only on the preview with sample data). 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: Notification type. created: type: boolean description: The template was created now. updated: type: boolean description: The existing template was overwritten with the default. id: type: - string - "null" format: uuid description: ID of the created or updated template. error: type: - string - "null" description: Why this type failed, when it did. required: - type - created - updated - id - error required: - data EmailLayoutV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Public identifier of the layout. organization_id: type: string format: uuid description: Organization that owns the layout. name: type: string description: Layout name. html_body: type: string description: HTML document email bodies are wrapped in, at the `{{content}}` placeholder. E-mails carrying a sign-in link or code always use the platform layout. is_default: type: boolean description: Whether this is the organization's default layout (at most one). is_active: type: boolean description: Whether the layout is active. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary organization-defined metadata (key/value). 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: Layout name (required on create). html_body: type: string description: HTML document containing the `{{content}}` placeholder (required on create; without it, 422). is_default: type: boolean description: Makes this the default layout; the previous default stops being one. required: - name - html_body EmailLayoutUpdateRequest: type: object properties: name: type: string description: Layout name (required on create). html_body: type: string description: HTML document containing the `{{content}}` placeholder (required on create; without it, 422). is_default: type: boolean description: Makes this the default layout; the previous default stops being one. is_active: type: boolean description: Activates or deactivates the layout. NotificationV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Public identifier of the notification. workspace_id: type: - string - "null" format: uuid description: Workspace of the notification. `null` for an organization-wide notification. 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: Notification type. channel: type: string enum: - email - in_app - webhook description: Delivery channel. status: type: string enum: - pending - sent - delivered - failed - read - skipped description: "`pending` (queued), `sent`, `delivered`, `read`, `failed` or `skipped` (not sent because the type was inactive)." template_id: type: - string - "null" format: uuid description: Email template used, when there was one. recipient: type: string description: Destination address. recipient_type: type: - string - "null" description: "Recipient kind: `portal_user`, `dashboard_user`, `organization` or `external`." recipient_id: type: - string - "null" format: uuid description: Recipient ID, when it is a record. subject: type: - string - "null" description: Rendered subject. content: type: - string - "null" description: Rendered body. variables: type: object additionalProperties: {} description: Variables used to render (without the sender’s internal `__*` keys). sent_at: type: - string - "null" format: date-time description: When it was sent. delivered_at: type: - string - "null" format: date-time description: When it was delivered. read_at: type: - string - "null" format: date-time description: When it was read. failure_reason: type: - string - "null" description: Reason of the last delivery failure. retry_count: type: integer description: Delivery retries so far. scheduled_for: type: - string - "null" format: date-time description: Scheduled send time, when there is one. resource_type: type: - string - "null" description: Kind of record the notification refers to. resource_id: type: - string - "null" format: uuid description: ID of the record the notification refers to. 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: Name and type of the template used (list only). 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: "Notification type (required): picks the organization's active template, or the platform default." recipient: type: string description: Destination address (required) — an email for the `email` channel. channel: type: string enum: - email - in_app - webhook description: Delivery channel. Defaults to `email`. portal_user_id: type: - string - "null" format: uuid description: Portal user the notification is for; must belong to the organization (else 404). resource_type: type: - string - "null" description: Kind of the related record. resource_id: type: - string - "null" format: uuid description: ID (UUID) of the related record. scheduled_for: type: - string - "null" format: date-time description: ISO 8601 date-time to send at, instead of right away. variables: type: object additionalProperties: anyOf: - type: string - type: number - type: boolean - type: "null" - type: "null" description: "Values for the template variables: up to 100, names of letters, digits, `_`, `.` or `-`; values text (up to 10,000 characters), number, boolean or `null`." required: - type - recipient NotificationStatsResponse: type: object properties: data: type: object properties: total: type: integer description: Notifications created in the window. by_status: type: object additionalProperties: type: integer description: Count per status. by_channel: type: object additionalProperties: type: integer description: Count per channel. by_type: type: object additionalProperties: type: integer description: Count per type. delivery_rate: type: number description: (sent + delivered) / total, between 0 and 1. read_rate: type: number description: read / total, between 0 and 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: "Where the key is used: `api`, `dashboard` or `manage`." prefix: type: string description: Visible start of the key (`kb_xxxxxxxx...`), to recognise it without the secret. status: type: string enum: - active - disabled - revoked description: "`active`, `disabled` (can be re-enabled) or `revoked` (terminal)." notification_emails: type: array items: type: string description: "Who gets the expiry reminders. Empty: the creator." 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: "When the key expires (`null`: never)." rotated_at: type: - string - "null" format: date-time description: When the key was replaced by a successor. 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: The plaintext secret. Shown only in this response — store it now. 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: The plaintext secret. Shown only in this response — store it now. 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: End of the previous key grace period. required: - id - rotated_at - grace_until description: The replaced key and until when it keeps working. 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: Key name (required). description: type: - string - "null" source: type: string enum: - api - dashboard - manage description: Where the key will be used. Default `dashboard`. notification_emails: type: array items: type: string description: E-mails that get the expiry reminders. expires_at: type: string format: date-time description: "Expiry (ISO 8601 date-time in the future). Default: one year from now." 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 that get the expiry reminders. expires_at: type: - string - "null" format: date-time description: New expiry (ISO 8601); `null` removes the expiry. enabled: type: boolean description: "`false` disables the key; `true` re-enables it." ApiKeyRotateRequest: type: object properties: grace_days: type: integer minimum: 0 maximum: 30 description: Days the previous key keeps working (0 to 30, default 7). ExportV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid resource_type: type: string description: Exported resource. format: type: string enum: - csv - xlsx - json status: type: string enum: - pending - processing - completed - failed description: "`pending`, `processing`, `completed` or `failed`." file_name: type: - string - "null" file_size_bytes: type: - integer - "null" total_rows: type: - integer - "null" filters: type: object additionalProperties: {} description: Filters applied to the exported rows. error_message: type: - string - "null" download_available: type: boolean description: "`true` when the file can be downloaded from `/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: When the file stops being available. 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: "What to export. Today: `portal_users`." format: type: string enum: - csv - xlsx - json description: "`csv` (default), `xlsx` or `json`." filters: type: object additionalProperties: {} description: Optional filters of the exported rows. required: - resource_type ImportV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid resource_type: type: string description: Imported resource. status: type: string enum: - pending - processing - completed - completed_with_errors - failed description: "`pending`, `processing`, `completed`, `completed_with_errors` or `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: Per-row errors recorded while processing. 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: "What to import. Today: `portal_users`." file_name: type: string minLength: 1 description: Original file name, e.g. `users.csv`. content_type: type: string description: File type. Default `text/csv`. content_base64: type: string minLength: 1 description: The CSV, base64-encoded. 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` (generated copy) or `restore`." 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: Number of records per resource in the file. progress: type: integer description: Progress from 0 to 100. current_resource: type: - string - "null" error_message: type: - string - "null" requested_by: type: - string - "null" description: Who asked (e-mail, or `api:` for a machine token). download_available: type: boolean description: "`true` when the ZIP of a completed backup can be downloaded." 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: Whether a new backup may be requested now. next_backup_at: type: - string - "null" format: date-time description: When the next backup becomes available (`null` when it already is). 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: Completed backup of this organization to restore. file_name: type: string description: "`.zip` file name, together with `content_base64`." content_base64: type: string description: The backup ZIP in 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: Rows per resource, across every workspace. 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: "What to purge: `portal_users`, `people`, `usage_history`." confirm: type: string description: "Confirmation: the organization id, typed back." required: - resources - confirm DataPurgeQueuedV1: type: object properties: job_id: type: string description: Purge job id. 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: "Queue job state: `waiting`, `active`, `completed`, `failed`…" progress: type: number description: Progress from 0 to 100. result: description: Job result once done (rows deleted per resource). 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: Number of names changed. 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: Support e-mail shown to customers. timezone: type: string description: IANA timezone (default `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: "Records options: upper-case names and what the dashboard allows creating or editing." 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: IANA timezone, e.g. `America/Sao_Paulo`. crm_uppercase_names: type: boolean description: Save names in UPPERCASE. 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: Allow creating portal users from the dashboard and by import. 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: Metric identifier. current: type: - number - "null" description: Value of the latest day in the range. peak: type: - number - "null" description: Highest value in the range. 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: Organization month to date. 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: Courtesy grant in force. org_cap_usd: type: - string - "null" description: Organization monthly cap, when there is one. 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: Whether the next AI turn is allowed and who funds it. 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: Price in US dollars, as a decimal string. required: - start_date - end_date - turns - prompt_tokens - completion_tokens - total_tokens - price_usd description: Workspace totals in the period. 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: Price in US dollars, as a decimal string. 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: Limits in force. has_custom_config: type: boolean description: "`true` when the organization has its own configuration." 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: Platform defaults. 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: Entity field that gives the user tenant ID. 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: "The tenant ID source changed: the next sync rewrites it on existing users." 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: Workspace entities that can be mapped, with their fields. 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: Outcome of the sync run now. 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: The entity whose records become portal users. 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: Display name of the file (by default the original name, with its extension). url: type: string description: "Link for whoever may open the file: the storage URL when `public`, the portal route when `restricted` (signed-in portal users) and the dashboard route when `private`." download_url: type: string description: API path that returns the file content to the token, whatever the visibility. visibility: type: string enum: - public - restricted - private description: "Who may download it: `public` (anyone with the link), `restricted` (users signed in to the workspace portal) or `private` (dashboard members only). New files start `restricted`." content_type: type: string example: image/png size_bytes: type: integer description: Size in bytes. kind: type: string enum: - image - document - other description: "`image`, `document` or `other`, derived from the file type." alt_text: type: - string - "null" description: Alternative text of an image (accessibility). source: type: string enum: - upload - chat - ai description: "How the file came in: `upload` (dashboard or API), `chat` (sent in the builder chat) or `ai` (saved by the builder AI)." created_by_email: type: - string - "null" description: E-mail of whoever uploaded the file, when known. created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - name - url - download_url - visibility - content_type - size_bytes - kind - alt_text - source - created_by_email - created_at - updated_at AssetResponse: type: object properties: data: $ref: "#/components/schemas/AssetV1" required: - data AssetListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/AssetV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta AssetCreateRequest: type: object properties: name: type: string description: Display name, with its extension (required). The extension decides the accepted type when `content_type` is absent. key: type: string description: The `key` returned by `POST /assets/presign`, after sending the file to the signed URL. Send `key` or `content_base64`, never both. content_base64: type: string description: "The file content in base64, for small files: the request body is capped at 2 MB (about 1.5 MB of file). For bigger files, use `POST /assets/presign`." content_type: type: string description: "MIME type. When omitted, it is guessed from the extension. Accepted: PNG, JPEG, GIF, WebP and AVIF images; PDF, text, CSV, Markdown, JSON, XML, Office and ZIP. SVG and HTML are not accepted." alt_text: type: string description: Alternative text of an image (accessibility). visibility: type: string enum: - public - restricted - private description: "Who may download it: `public` (anyone with the link), `restricted` (users signed in to the workspace portal) or `private` (dashboard members only). New files start `restricted`." required: - name AssetUpdateRequest: type: object properties: name: type: string description: Display name of the file (by default the original name, with its extension). alt_text: type: - string - "null" description: Alternative text of an image. Send `null` to clear it. visibility: type: string enum: - public - restricted - private description: "Who may download it: `public` (anyone with the link), `restricted` (users signed in to the workspace portal) or `private` (dashboard members only). New files start `restricted`." AssetPresignRequest: type: object properties: filename: type: string description: File name with its extension. content_type: type: string description: "MIME type. When omitted, it is guessed from the extension. Accepted: PNG, JPEG, GIF, WebP and AVIF images; PDF, text, CSV, Markdown, JSON, XML, Office and ZIP. SVG and HTML are not accepted." size: type: integer exclusiveMinimum: 0 description: Exact size, in bytes, of the file you will send (max 25 MB). required: - filename - size AssetPresignResponse: type: object properties: data: type: object properties: url: type: string description: Short-lived signed URL to send the file to with `PUT`. method: type: string enum: - PUT headers: type: object additionalProperties: type: string description: Headers the `PUT` must carry exactly as they are. key: type: string description: "Storage key of the file: send it to `POST /assets` to record it." content_type: type: string description: MIME type resolved for the file. required: - url - method - headers - key - content_type required: - data DashboardUserUpsertResponse: type: object properties: data: $ref: "#/components/schemas/DashboardUserV1" matched_by: type: - string - "null" description: Key that located the existing record. `null` when the record was created. required: - data - matched_by DashboardUserUpsertRequest: type: object properties: email: type: string format: email description: User's email. Besides being a resource field, it doubles as the natural lookup key. name: type: string description: User name (optional — may be filled in by the user on first login). external_id: type: string description: "External user identifier, stored as an attribute of the member. It does not define the user identity: that is always resolved by `email`." role_ids: type: array items: type: string format: uuid minItems: 1 description: List of role UUIDs (`team_roles`) to assign to the user. Must contain at least one item. permissions: type: array items: type: string description: Additional ad-hoc permissions (on top of those inherited from roles). Accepts the same permission slugs. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). id: type: string format: uuid description: Record UUID. Used only to locate it — never written. public_id: type: string format: uuid description: Public UUID of the record, used to locate it. TeamRoleUpsertResponse: type: object properties: data: $ref: "#/components/schemas/TeamRoleV1" matched_by: type: - string - "null" description: Key that located the existing record. `null` when the record was created. required: - data - matched_by TeamRoleUpsertRequest: type: object properties: name: type: string minLength: 1 description: Role name (shown in the UI). slug: type: string pattern: ^[a-z][a-z0-9_]*$ description: "Stable slug used to reference the role (e.g.: `support_manager`)." example: portal_manager description: type: string description: Optional description of what the role grants. permissions: type: array items: type: string description: List of permission slugs granted by the role. is_active: type: boolean description: Indicates whether the role is active and can be assigned. external_id: type: string description: Identifier in your external system, for idempotency/sync. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). id: type: string format: uuid description: Record UUID. Used only to locate it — never written. public_id: type: string format: uuid description: Public UUID of the record, used to locate it. parameters: {} securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: "Send the `Authorization: Bearer ` header. The token is an RS256 access token issued by the Kobana authorization server (`account.kobana.com.br`), with `aud` equal to `https://api.dashboards.kobana.com.br` and a required `exp`. The `org` claim (the Kobana account) is what scopes the data and is required too; `sub` is the **person** and is carried for audit. This API only verifies tokens — it issues none. The `scope` claim is enforced too: a `GET` needs `read`, `write` or `all`, and any other method needs `write` or `all` — otherwise the answer is `403 insufficient_scope`, with `{ required, granted }` in `details`. A token issued to a **person** (`src` `user` or `oauth`) is also bounded by what that person may do in the dashboard: the operation needs the matching permission of their role (otherwise `403 insufficient_permission`, with `{ required }` in `details`), and someone who is not an active member of the organization is refused. A person token whose `sub` this app cannot identify returns `401 invalid_token`. Machine tokens (`src` `system` or `api`) act for the organization." paths: /v1/organization: get: tags: - Organization summary: Get current organization description: Returns the data of the organization the authenticated token belongs to. There is no `:id` parameter — the organization is always resolved from the API key. security: - bearerAuth: [] responses: "200": description: Current organization detail. content: application/json: schema: $ref: "#/components/schemas/OrganizationResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-organization parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier patch: tags: - Organization summary: Update current organization description: Updates the profile of the authenticated organization. Only the fields below can be modified — identity (`id`, `external_id`, `status`) is not changeable through this endpoint. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/OrganizationUpdateRequest" responses: "200": description: Organization updated. content: application/json: schema: $ref: "#/components/schemas/OrganizationResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-organization parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/me: get: tags: - Organization summary: Current token identity description: "Returns who is behind the Bearer token: the person (`user`, `null` for a machine token), the organization, and the token's own scopes, access level and expiry. Use it to check that the credential configured in an integration is valid. It never returns the token, hashes or keys." security: - bearerAuth: [] responses: "200": description: Identity of the authenticated token. content: application/json: schema: $ref: "#/components/schemas/MeResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-me parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/portal_users: get: tags: - Portal Users summary: List portal users description: Returns the workspace's portal users, paginated. Sensitive fields (password, tokens) are never exposed. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string description: Scope to the users of one owner ID (exact match). required: false name: tenant_id in: query - schema: type: string enum: - active - pending_verification - pending_invitation - suspended - locked description: "Filter by status: `active`, `pending_invitation`, `pending_verification`, `suspended` or `locked`." required: false name: status in: query - schema: type: string description: Substring match on the email. required: false name: email in: query - schema: type: string description: Filter by the exact `external_id`. required: false name: external_id in: query - schema: type: string enum: - "true" - "false" description: Filter by `sso_only` (`true` or `false`). required: false name: sso_only in: query - schema: type: string description: Start of creation date range (YYYY-MM-DD). required: false name: created_after in: query - schema: type: string description: End of creation date range (YYYY-MM-DD). required: false name: created_before in: query - schema: type: string description: Last sign-in on or after this date (ISO 8601). required: false name: last_login_after in: query - schema: type: string description: Last sign-in on or before this date (ISO 8601). required: false name: last_login_before in: query - schema: type: string format: uuid description: Filter by associated person UUID. required: false name: person_id in: query - schema: type: string description: Filter by person CPF/CNPJ (exact match). required: false name: person_document_number in: query - schema: type: string description: Filter by person name (partial search, case-insensitive). required: false name: person_name_contains in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of portal users. content: application/json: schema: $ref: "#/components/schemas/PortalUserListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-portal-users post: tags: - Portal Users summary: Create (invite) portal user description: Creates the user in the workspace with status `pending_invitation` and sends the invitation email. The invitation expires in 7 days. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PortalUserCreateRequest" responses: "201": description: Invitation created and email queued for sending. content: application/json: schema: $ref: "#/components/schemas/PortalUserResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: A user or invitation already exists for this email in the workspace. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-portal-users parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/portal_users/invite: post: tags: - Portal Users summary: Invite portal user (verb) description: Equivalent to `POST /portal_users`. Available as a verb route for SDKs that prefer descriptive URLs. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PortalUserCreateRequest" responses: "201": description: Invitation created and email queued for sending. content: application/json: schema: $ref: "#/components/schemas/PortalUserResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: A user or invitation already exists for this email in the workspace. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-portal-users-invite parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/portal_users/{id}: get: tags: - Portal Users summary: Get portal user description: The `{id}` parameter accepts the user's UUID or `external_id`. security: - bearerAuth: [] parameters: - schema: type: string description: Portal user UUID or its `external_id`. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Portal user detail. content: application/json: schema: $ref: "#/components/schemas/PortalUserResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-portal-users-id patch: tags: - Portal Users summary: Update portal user description: "Updates `email`, `tenant_id`, `external_id`, `sso_only`, `status` and `custom_metadata`. Allowed status transitions: `active` ↔ `suspended`." security: - bearerAuth: [] parameters: - schema: type: string description: Portal user UUID or its `external_id`. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `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: User updated. content: application/json: schema: $ref: "#/components/schemas/PortalUserResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: A user or invitation already exists for this email in the workspace. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-portal-users-id delete: tags: - Portal Users summary: Remove portal user description: Pending invitations are permanently removed; other users are suspended. security: - bearerAuth: [] parameters: - schema: type: string description: Portal user UUID or its `external_id`. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Removal confirmation. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-portal-users-id /v1/portal_users/{id}/email-preview: get: tags: - Portal Users summary: Preview portal user email description: Returns the subject and body of the invitation or verification email that would be sent to the user, without actually sending it. Available only for `pending_invitation` or `pending_verification` users. security: - bearerAuth: [] parameters: - schema: type: string description: Portal user UUID or its `external_id`. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Email preview. content: application/json: schema: $ref: "#/components/schemas/PortalUserEmailPreviewResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-portal-users-id-email-preview /v1/portal_users/{id}/resend: post: tags: - Portal Users summary: Resend invitation or verification email description: Resends the invitation email (for `pending_invitation`, rotating the token) or verification email (for `pending_verification`). Other statuses return 400. security: - bearerAuth: [] parameters: - schema: type: string description: Portal user UUID or its `external_id`. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Email resent. content: application/json: schema: $ref: "#/components/schemas/PortalUserResendResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-portal-users-id-resend /v1/dashboard_users: get: tags: - Account Administration summary: List dashboard users description: Returns a paginated list of dashboard users (team members) for the current organization. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string description: Text search by name or email. required: false name: search in: query - schema: type: string enum: - all - active - pending_invitation - suspended description: "Filter by status: `all` (default), `active`, `pending_invitation` or `suspended`." required: false name: status in: query - schema: type: string description: Filter by users that have the given role (role slug). required: false name: role in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of dashboard users. content: application/json: schema: $ref: "#/components/schemas/DashboardUserListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-dashboard-users post: tags: - Account Administration summary: Invite dashboard user description: Invites a new member to the organization team. `email` and at least one role in `role_ids` are required. The user receives an email invite and starts with `pending_invitation` status. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/DashboardUserCreateRequest" responses: "201": description: User invited. content: application/json: schema: $ref: "#/components/schemas/DashboardUserResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Invalid data. With code `IDENTITY_CONFLICT`, the given `external_id` is the identifier of another identity, with a different email. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-dashboard-users parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier put: tags: - Account Administration summary: Create or update a dashboard user description: Looks the user up by `id`, `public_id`, `external_id` or `email` — the last one is unique per organization. If found, updates it; otherwise creates it and returns `201`. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/DashboardUserUpsertRequest" responses: "200": description: Record updated. content: application/json: schema: $ref: "#/components/schemas/DashboardUserUpsertResponse" "201": description: Record created. content: application/json: schema: $ref: "#/components/schemas/DashboardUserUpsertResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Invalid data. With code `IDENTITY_CONFLICT`, the given `external_id` is the identifier of another identity, with a different email. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-dashboard-users parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/dashboard_users/{id}: get: tags: - Account Administration summary: Get dashboard user security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Dashboard user UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Dashboard user detail. content: application/json: schema: $ref: "#/components/schemas/DashboardUserResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-dashboard-users-id patch: tags: - Account Administration summary: Update dashboard user description: Updates the user’s name, picture, status, permissions and/or roles. Only the fields sent are changed. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Dashboard user UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `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: User updated. content: application/json: schema: $ref: "#/components/schemas/DashboardUserResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-dashboard-users-id delete: tags: - Account Administration summary: Remove dashboard user description: Removes the dashboard user from the organization. Irreversible — the user must be invited again to regain access. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Dashboard user UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: User removed. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-dashboard-users-id /v1/team_roles: get: tags: - Account Administration summary: List team roles description: Returns the paginated list of roles configured for the organization team. Includes both system roles (`is_system = true`) and custom roles. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string description: Text search by name or slug. required: false name: search in: query - schema: type: - boolean - "null" description: Filter by active (`true`) or inactive (`false`) roles. required: false name: is_active in: query - schema: type: - boolean - "null" description: Filter by system (`true`) or custom (`false`) roles. required: false name: is_system in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of roles. content: application/json: schema: $ref: "#/components/schemas/TeamRoleListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-team-roles post: tags: - Account Administration summary: Create custom role description: Creates a custom role. `slug` must start with a lowercase letter and contain only lowercase letters, digits and `_`. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/TeamRoleCreateRequest" responses: "201": description: Role created. content: application/json: schema: $ref: "#/components/schemas/TeamRoleResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-team-roles parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier put: tags: - Account Administration summary: Create or update a team role description: Looks the role up by `id`, `public_id` or `external_id`. The `slug` carries no unique constraint and therefore does **not** identify a row. If found, updates it; otherwise creates it and returns `201`. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/TeamRoleUpsertRequest" responses: "200": description: Record updated. content: application/json: schema: $ref: "#/components/schemas/TeamRoleUpsertResponse" "201": description: Record created. content: application/json: schema: $ref: "#/components/schemas/TeamRoleUpsertResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-team-roles parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/team_roles/{id}: get: tags: - Account Administration summary: Get role security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Role UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Role detail. content: application/json: schema: $ref: "#/components/schemas/TeamRoleResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-team-roles-id patch: tags: - Account Administration summary: Update role description: Updates the role fields. Only the fields sent are changed. System roles have additional restrictions. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Role UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `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: Role updated. content: application/json: schema: $ref: "#/components/schemas/TeamRoleResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-team-roles-id delete: tags: - Account Administration summary: Remove role description: Soft-deletes the role. System roles (`is_system = true`) cannot be removed. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Role UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Role removed. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-team-roles-id /v1/workspaces: get: tags: - Workspaces summary: List workspaces description: Lists the workspaces of the organization you can open, with your role in each — the same ones as the dashboard switcher. A machine token sees every workspace of the organization. Does not require `X-Workspace-Id`. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string description: Substring of the workspace name, case-insensitive. required: false name: search in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Page of workspaces. content: application/json: schema: $ref: "#/components/schemas/WorkspaceListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-workspaces post: tags: - Workspaces summary: Create workspace description: "Creates an empty workspace in the organization. The token person becomes its owner. Created by a machine token, the workspace has no owner: the organization owners receive it on their next sign-in, and `PUT /dashboard_users/{id}/workspaces` grants it to other members." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/WorkspaceWriteRequest" responses: "201": description: Workspace created. content: application/json: schema: $ref: "#/components/schemas/WorkspaceResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-workspaces parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/workspaces/import: post: tags: - Workspaces summary: Import workspace description: Restores a file from `GET /workspaces/{id}/export` into a NEW workspace owned by the token person. Answers what could not be brought back (`warnings`) so it can be finished by hand. Requires a person token (a machine token gets 403) holding the permissions to create workspaces, configure the portal and create data sources. The entities in the file go through the same checks as when created one by one (keys, expressions, the field limit of the workspace). The body is limited to 2 MB. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/WorkspaceImportRequest" responses: "201": description: Workspace imported. content: application/json: schema: $ref: "#/components/schemas/WorkspaceImportResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: The file is not a valid workspace export (`INVALID_WORKSPACE_FILE`). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-workspaces-import parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/workspaces/{id}: get: tags: - Workspaces summary: Get workspace description: Returns a workspace you can open. A workspace you hold no grant on answers 404. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Workspace ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Workspace found. content: application/json: schema: $ref: "#/components/schemas/WorkspaceResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-workspaces-id patch: tags: - Workspaces summary: Rename workspace description: Renames the workspace. Only the workspace owners can (403 for a plain member). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Workspace ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `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 renamed. content: application/json: schema: $ref: "#/components/schemas/WorkspaceResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-workspaces-id delete: tags: - Workspaces summary: Delete workspace description: "Deletes the workspace (soft delete), for its owners only: the portal goes offline, connectors stop syncing and members lose access. The last workspace of the organization cannot be deleted." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Workspace ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Workspace deleted. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: It is the last workspace of the organization (`WORKSPACE_LAST`). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-workspaces-id /v1/workspaces/{id}/usage: get: tags: - Workspaces summary: Get workspace usage description: Counts what deleting the workspace would hide — the same summary as the dashboard delete dialog. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Workspace ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Workspace counts. content: application/json: schema: $ref: "#/components/schemas/WorkspaceUsageResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-workspaces-id-usage /v1/workspaces/{id}/export: get: tags: - Workspaces summary: Export workspace description: Downloads the workspace configuration (portal builder, portal access and settings, user mapping, connectors and entities) as a JSON file, for its owners only. Secrets and data stay out. The response is the file itself, with no `data` envelope; send it as `data` to `POST /workspaces/import`. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Workspace ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: "Export file (`Content-Disposition: attachment`)." content: application/json: schema: $ref: "#/components/schemas/WorkspaceExportFile" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-workspaces-id-export /v1/dashboard_users/{id}/workspaces: get: tags: - Account Administration summary: Get member workspace access description: Lists every workspace of the organization, flagging the ones the member reaches — also the list of what can be granted. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Team member (dashboard user) ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Workspaces of the organization with the member access. content: application/json: schema: $ref: "#/components/schemas/WorkspaceGrantListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-dashboard-users-id-workspaces put: tags: - Account Administration summary: Set member workspace access description: Replaces the member set of workspaces. Nobody changes their own access (400), only an owner changes an owner access, and only an owner grants or revokes a workspace they cannot open themselves (403). A machine token may grant any workspace but never changes an owner access. Removing the last owner of a workspace answers 403. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Team member (dashboard user) ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `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 of the organization with the member access. content: application/json: schema: $ref: "#/components/schemas/WorkspaceGrantListResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-dashboard-users-id-workspaces /v1/dashboard_users/{id}/resend: post: tags: - Account Administration summary: Resend member invitation description: Re-sends the invitation e-mail, with a fresh sign-in link, to a member whose invitation is still pending. Capped at 5 e-mails per hour per recipient (429 above that). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Team member (dashboard user) ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Invitation re-sent. content: application/json: schema: $ref: "#/components/schemas/DashboardUserResendResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: The member has no pending invitation (`INVALID_STATUS`). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "502": description: The e-mail could not be sent (`EMAIL_ERROR`). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-dashboard-users-id-resend /v1/permissions: get: tags: - Account Administration summary: List permissions description: Catalog of the dashboard permissions a member or a team role can carry, grouped by resource — the vocabulary of `permissions` on `/dashboard_users` and `/team_roles`. security: - bearerAuth: [] responses: "200": description: Permission groups. content: application/json: schema: $ref: "#/components/schemas/PermissionCatalogResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-permissions parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/data_sources: get: tags: - Data Sources summary: List data sources description: "Data sources of the workspace — OpenAPI APIs, MCP servers and read-only databases — newest first. Secrets are never returned. To create a source, use the route of its kind: `/data_sources/openapi`, `/mcp`, `/database` or `/catalog`." security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Page of data sources. content: application/json: schema: $ref: "#/components/schemas/DataSourceListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-data-sources /v1/data_sources/catalog: get: tags: - Data Sources summary: List Kobana catalog products description: Kobana products that can be connected as a data source with just a token. Whole list, unpaginated. security: - bearerAuth: [] responses: "200": description: Catalog products. content: application/json: schema: $ref: "#/components/schemas/DataSourceCatalogResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-data-sources-catalog parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier post: tags: - Data Sources summary: Connect a Kobana product description: Saves an OpenAPI source from the product spec shipped with the app and tests the connection. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/DataSourceCatalogConnectRequest" responses: "201": description: Source created, with the outcome of the connection test. content: application/json: schema: $ref: "#/components/schemas/DataSourceCreatedResponse" "400": description: Body that is not JSON, or a field of the wrong type. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: A data source with this name already exists in the workspace. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-data-sources-catalog parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/data_sources/openapi: post: tags: - Data Sources summary: Create an OpenAPI data source description: Saves an API described by an OpenAPI spec, imports its operations and tests the connection. The spec goes as text in `spec`; the mTLS certificate, base64-encoded in `certificate`. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/DataSourceOpenApiCreateRequest" responses: "201": description: Source created, with the outcome of the connection test. content: application/json: schema: $ref: "#/components/schemas/DataSourceCreatedResponse" "400": description: Body that is not JSON, or a field of the wrong type. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: A data source with this name already exists in the workspace. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-data-sources-openapi parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/data_sources/openapi/analyze: post: tags: - Data Sources summary: Analyze an OpenAPI spec description: Reads the spec and returns what would be imported — title, servers, security schemes, suggested auth and operations — without saving anything. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/DataSourceSpecRequest" responses: "200": description: Spec analysis. content: application/json: schema: $ref: "#/components/schemas/DataSourceSpecAnalysisResponse" "400": description: Body that is not JSON, or a field of the wrong type. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-data-sources-openapi-analyze parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/data_sources/mcp: post: tags: - Data Sources summary: Create an MCP data source description: Saves an MCP server. Without OAuth it connects and discovers the tools right away; with OAuth it returns `authorization_url`, which a person signed in to the dashboard must open in a browser to finish. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/DataSourceMcpCreateRequest" responses: "201": description: Source created, with the outcome of the connection test. content: application/json: schema: $ref: "#/components/schemas/DataSourceMcpCreatedResponse" "400": description: Body that is not JSON, or a field of the wrong type. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: A data source with this name already exists in the workspace. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-data-sources-mcp parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/data_sources/database: post: tags: - Data Sources summary: Create a database data source description: Saves a read-only database (PostgreSQL, MySQL, MariaDB, SQL Server or MongoDB), connects and catalogs its tables or collections. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/DataSourceDatabaseCreateRequest" responses: "201": description: Source created, with the outcome of the connection test. content: application/json: schema: $ref: "#/components/schemas/DataSourceCreatedResponse" "400": description: Body that is not JSON, or a field of the wrong type. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: A data source with this name already exists in the workspace. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-data-sources-database parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/data_sources/test: post: tags: - Data Sources summary: Test a connection before saving description: Tests a connection that is not saved yet. Send `kind` (`openapi`, `mcp`, `database` or `catalog`) and the body of the matching create route. Nothing is persisted. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/DataSourceDraftTestRequest" responses: "200": description: Outcome of the connection test. content: application/json: schema: $ref: "#/components/schemas/DataSourceDraftTestResponse" "400": description: Body that is not JSON, or a field of the wrong type. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-data-sources-test parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/data_sources/{id}: get: tags: - Data Sources summary: Get a data source description: The data source and its operations (endpoints, tools or tables it can read). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Data source ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Data source with its operations. content: application/json: schema: $ref: "#/components/schemas/DataSourceDetailResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-data-sources-id patch: tags: - Data Sources summary: Update a data source description: Updates the name, `is_active` and the connection fields of the kind of the source. Blank secret fields keep the stored ones. An OpenAPI source takes a new certificate in `certificate`. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Data source ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `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: Updated data source. content: application/json: schema: $ref: "#/components/schemas/DataSourceResponse" "400": description: Body that is not JSON, or a field of the wrong type. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: A data source with this name already exists in the workspace. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-data-sources-id delete: tags: - Data Sources summary: Delete a data source description: Removes the source, its operations and its sync schedule. Entities fed by it stop syncing. Cannot be undone. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Data source ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Source deleted. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-data-sources-id /v1/data_sources/{id}/test: post: tags: - Data Sources summary: Test a data source description: Tests the saved source and records the outcome (status, last error). For an MCP server it also refreshes the tool list. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Data source ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Outcome of the connection test. content: application/json: schema: $ref: "#/components/schemas/DataSourceTestResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-data-sources-id-test /v1/data_sources/{id}/sync: post: tags: - Data Sources summary: Sync a data source description: Queues a sync of every entity fed by the source. The run is asynchronous. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Data source ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `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: Sync queued. content: application/json: schema: $ref: "#/components/schemas/DataSourceSyncResponse" "400": description: Body that is not JSON, or a field of the wrong type. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: "Limit exceeded: the API request rate limit, or the organization's budget of queued syncs (60 per hour, across every data source) — code `rate_limited`. Wait for the time given in `Retry-After` and try again." headers: Retry-After: description: Seconds until the organization may queue another sync. schema: type: integer content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-data-sources-id-sync /v1/data_sources/{id}/schedule: put: tags: - Data Sources summary: Schedule the sync of a data source description: "Sets how often the source syncs: `{ cron, timezone }`, or `{ cron: null }` for on demand only. Returns the next runs." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Data source ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `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: Schedule saved. content: application/json: schema: $ref: "#/components/schemas/DataSourceScheduleResponse" "400": description: Body that is not JSON, or a field of the wrong type. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-data-sources-id-schedule /v1/data_sources/{id}/spec: put: tags: - Data Sources summary: Replace the spec of a data source description: "Replaces the OpenAPI spec and re-syncs the operations: those that keep their key keep their settings; those gone from the spec are removed." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Data source ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `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 replaced, with the warnings of the analysis. content: application/json: schema: $ref: "#/components/schemas/DataSourceSpecResponse" "400": description: Body that is not JSON, or a field of the wrong type. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-data-sources-id-spec /v1/data_sources/{id}/authorize: post: tags: - Data Sources summary: Authorize an MCP data source description: Restarts the OAuth authorization of an MCP server. Returns `authorization_url` for a person signed in to the dashboard to open in a browser, or `null` plus the connection test when the stored tokens still work. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Data source ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Authorization URL or test outcome. content: application/json: schema: $ref: "#/components/schemas/DataSourceAuthorizeResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-data-sources-id-authorize /v1/data_sources/{id}/logs: get: tags: - Data Sources summary: List the request log of a data source description: Calls the source made (HTTP requests, database queries), newest first, without headers nor bodies. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Data source ID (UUID). required: true name: id in: path - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string description: HTTP method (GET, POST…). required: false name: method in: query - schema: type: string enum: - "true" - "false" description: "`true` for successful calls only, `false` for failed ones only." required: false name: success in: query - schema: type: string description: Substring of the endpoint, case-insensitive. required: false name: search in: query - schema: type: string format: date description: From this day (YYYY-MM-DD, UTC), inclusive. required: false name: date_from in: query - schema: type: string format: date description: Up to this day (YYYY-MM-DD, UTC), inclusive. required: false name: date_to in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Page of the request log. content: application/json: schema: $ref: "#/components/schemas/DataSourceRequestLogListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-data-sources-id-logs /v1/data_sources/{id}/logs/{log_id}: get: tags: - Data Sources summary: Get a request of a data source description: "One call, whole: request and response headers and bodies, with secrets masked." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Data source ID (UUID). required: true name: id in: path - schema: type: string format: uuid description: Request log entry ID. required: true name: log_id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Request log entry. content: application/json: schema: $ref: "#/components/schemas/DataSourceRequestLogResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. 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: - Data Sources summary: Enable or disable an operation of a data source description: Turns one operation of the source on or off (`enabled`). Disabled operations do not feed entities. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Data source ID (UUID). required: true name: id in: path - schema: type: string format: uuid description: ID of the operation of the source. required: true name: operation_id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `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: Updated operation. content: application/json: schema: $ref: "#/components/schemas/DataSourceOperationResponse" "400": description: Body that is not JSON, or a field of the wrong type. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-data-sources-id-operations-operation-id /v1/entities: get: tags: - Entities summary: List entities description: Every entity of the workspace, with fields, source and sync state, ordered by name. Not paginated. security: - bearerAuth: [] responses: "200": description: Entities of the workspace. content: application/json: schema: $ref: "#/components/schemas/EntityListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-entities parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier post: tags: - Entities summary: Create entity description: Registers an entity from a read operation (or SQL query) of the data source with the chosen fields, and queues its first full sync. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/EntityCreateRequest" responses: "201": description: Entity created. content: application/json: schema: $ref: "#/components/schemas/EntityResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: "Conflict: key already used in the workspace, or the entity is read by a relation." content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-entities parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/entities/preview: post: tags: - Entities summary: Preview a source description: Calls the chosen read operation (or runs the SQL query) and returns the sample with the entity inferred from it. Nothing is stored; the call is kept in the connector's request log. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/EntityPreviewRequest" responses: "200": description: Sample and inferred entity. content: application/json: schema: $ref: "#/components/schemas/EntityPreviewResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-entities-preview parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/entities/join: post: tags: - Entities summary: Create join entity description: Registers an entity that relates two others (a join) with the fields picked from each, and queues its first sync. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/EntityJoinRequest" responses: "201": description: Entity created. content: application/json: schema: $ref: "#/components/schemas/EntityResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: "Conflict: key already used in the workspace, or the entity is read by a relation." content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-entities-join parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/entities/join/preview: post: tags: - Entities summary: Preview a relation description: How two entities match on the given fields (counts) and the first combined rows, before the relation is saved. Reads stored records only. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/EntityJoinSpecV1" responses: "200": description: Relation preview. content: application/json: schema: $ref: "#/components/schemas/EntityJoinPreviewResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-entities-join-preview parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/entities/{id}: get: tags: - Entities summary: Get entity description: One entity with its fields, source, sync mode, owner field and sync state. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Entity ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: The entity. content: application/json: schema: $ref: "#/components/schemas/EntityResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-entities-id patch: tags: - Entities summary: Update entity description: Name, key, special fields, the sync's pagination, filters and mode, and the field list (matched by key). When the mapping changes, the records are re-read. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Entity ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `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: Entity updated. content: application/json: schema: $ref: "#/components/schemas/EntityResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: "Conflict: key already used in the workspace, or the entity is read by a relation." content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-entities-id delete: tags: - Entities summary: Delete entity description: Soft-deletes the entity and its fields. Refused (409) while a join entity reads it. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Entity ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Entity deleted. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: "Conflict: key already used in the workspace, or the entity is read by a relation." content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-entities-id /v1/entities/{id}/join: put: tags: - Entities summary: Update relation description: Replaces the relation of a join entity and the fields it brings, then re-reads its records. 422 when the entity is not a join. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Entity ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `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: Entity updated. content: application/json: schema: $ref: "#/components/schemas/EntityResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: "Conflict: key already used in the workspace, or the entity is read by a relation." content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-entities-id-join /v1/entities/{id}/records: get: tags: - Entities summary: Query records description: The synced records of the entity, with field filters, sort and `limit`/`offset` paging (the same query the portal blocks run). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Entity ID (UUID). required: true name: id in: path - schema: type: integer minimum: 1 maximum: 200 description: Records per call (default 50, max 200). example: 50 required: false name: limit in: query - schema: type: - integer - "null" minimum: 0 maximum: 10000 description: How many records to skip. example: 0 required: false name: offset in: query - schema: type: string description: Field keys with an optional direction, comma-separated (`field:desc,other`); `asc` by default. example: due_date:desc,name required: false name: sort in: query - schema: type: string description: 'JSON object of field conditions: `{"field": value}` or `{"field": {"gte": 10}}`. Operators: `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: "A portal user ID: only that user's records, as the portal shows them (on an `on_access` entity, syncs that tenant first)." required: false name: preview_as in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Entity records. content: application/json: schema: $ref: "#/components/schemas/EntityRecordsQueryResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-entities-id-records delete: tags: - Entities summary: Clear records description: Removes every synced record of the entity and resets its sync state, so the next sync reads the source from scratch. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Entity ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Records removed. content: application/json: schema: $ref: "#/components/schemas/EntityRecordsClearedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-entities-id-records /v1/entities/{id}/records/{record_id}: get: tags: - Entities summary: Get record description: One synced record — values by field and the record as the source sent it — with its entity. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Entity ID (UUID). required: true name: id in: path - schema: type: string format: uuid description: Synced record ID (UUID) — the `_record.id` of a listed record. required: true name: record_id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: The record and its entity. content: application/json: schema: $ref: "#/components/schemas/EntityRecordResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-entities-id-records-record-id /v1/entities/{id}/aggregate: get: tags: - Entities summary: Aggregate records description: Count, sum, average, min or max over the synced records, optionally grouped by a field — what KPI and chart blocks show. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Entity ID (UUID). required: true name: id in: path - schema: type: string enum: - count - sum - avg - min - max description: "Aggregate: `count` (default), `sum`, `avg`, `min` or `max`." required: false name: op in: query - schema: type: string description: Key of the aggregated field (required except for `count`; numeric for `sum`/`avg`). required: false name: field in: query - schema: type: string description: Key of the field to group by. required: false name: group_by in: query - schema: type: string description: 'JSON object of field conditions: `{"field": value}` or `{"field": {"gte": 10}}`. Operators: `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: "A portal user ID: only that user's records, as the portal shows them (on an `on_access` entity, syncs that tenant first)." required: false name: preview_as in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Aggregate result. content: application/json: schema: $ref: "#/components/schemas/EntityAggregateResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-entities-id-aggregate /v1/entities/{id}/usage: get: tags: - Entities summary: Entity usage description: The portal pages (draft and published) whose blocks read the entity — what breaks if it is removed or its key changes. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Entity ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Pages using the entity. content: application/json: schema: $ref: "#/components/schemas/EntityUsageResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-entities-id-usage /v1/entities/{id}/logs: get: tags: - Entities summary: Sync log description: "The calls the entity's sync made to its connector, newest first: the connector's request log narrowed to the entity." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Entity ID (UUID). required: true name: id in: path - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: HTTP method of the call, such as `GET`. required: false name: method in: query - schema: type: string enum: - "true" - "false" description: Only successful (`true`) or failed (`false`) calls. required: false name: success in: query - schema: type: string description: Part of the endpoint called. required: false name: search in: query - schema: type: string format: date description: First day (YYYY-MM-DD). example: 2026-01-01 required: false name: date_from in: query - schema: type: string format: date description: Last day, inclusive (YYYY-MM-DD). example: 2026-01-31 required: false name: date_to in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Sync calls. content: application/json: schema: $ref: "#/components/schemas/EntitySyncLogListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-entities-id-logs /v1/entities/{id}/logs/{log_id}: get: tags: - Entities summary: Get sync call description: One call of the entity's sync, whole (secrets masked). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Entity ID (UUID). required: true name: id in: path - schema: type: string format: uuid description: ID (UUID) of the call in the request log. required: true name: log_id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: The call. content: application/json: schema: $ref: "#/components/schemas/EntitySyncLogResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-entities-id-logs-log-id /v1/entities/{id}/sync: post: tags: - Entities summary: Sync entity description: "Queues a sync of the entity and answers 202 with its ID; follow it at `GET /entities/{id}/sync`. An `on_access` entity has no entity-wide sync (422): use `POST /entities/{id}/tenant_syncs`." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Entity ID (UUID). required: true name: id in: path - schema: type: string enum: - "true" - "1" description: "`true` (or `1`) re-reads everything and drops what the source no longer has; without it the sync is incremental where the source allows." required: false name: full in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "202": description: Sync queued. content: application/json: schema: $ref: "#/components/schemas/EntitySyncQueuedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-entities-id-sync get: tags: - Entities summary: Sync state description: "Where the entity's sync stands: status, last error, last syncs, record count and stats." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Entity ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Sync state. content: application/json: schema: $ref: "#/components/schemas/EntitySyncStateResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-entities-id-sync /v1/entities/{id}/tenant_syncs: get: tags: - Entities summary: Tenant syncs description: "On an `on_access` entity: where each tenant's sync stands, most recently accessed first." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Entity ID (UUID). required: true name: id in: path - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string enum: - queued - running - completed - error description: Status of the tenant's sync. required: false name: status in: query - schema: type: string maxLength: 200 description: Part of the tenant ID. required: false name: search in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Tenant syncs. content: application/json: schema: $ref: "#/components/schemas/EntityTenantSyncListResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-entities-id-tenant-syncs post: tags: - Entities summary: Sync one tenant description: Queues one tenant's sync of an `on_access` entity now. 404 when no portal user carries that tenant ID; 422 when the entity is not `on_access`. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Entity ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `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: Sync queued. content: application/json: schema: $ref: "#/components/schemas/EntityTenantSyncQueuedResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-entities-id-tenant-syncs /v1/portal_builder: get: tags: - Portal Builder summary: Get the portal builder description: "Returns the workspace's portal as the builder sees it: portal identity, the draft (pages in menu order, each badged against the live version, `revision` and `dirty`), the live version number, the published versions, the theme and the SEO defaults. Read `revision` here before saving the draft." security: - bearerAuth: [] responses: "200": description: The portal builder. content: application/json: schema: $ref: "#/components/schemas/PortalBuilderResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-portal-builder parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/portal_builder/draft: put: tags: - Portal Builder summary: Save the portal draft description: "Replaces the whole draft — pages in menu order, editor state and, optionally, theme and SEO defaults — guarded by the `revision` you last read. A stale `revision` answers 409 and changes nothing. Nothing goes live: to publish, use `POST /portal_builder/publish`." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PortalBuilderDraftRequest" responses: "200": description: "Draft saved: the new `revision`, whether it differs from the live version and each page badge." content: application/json: schema: $ref: "#/components/schemas/PortalBuilderDraftSaveResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: "The `revision` sent is stale: someone (or another tab) saved the draft in between. Read it again and resend." content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-portal-builder-draft parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/portal_builder/publish: post: tags: - Portal Builder summary: Publish the portal description: "Saves the draft as sent (same body as the draft save, plus an optional `note`) and freezes it into the next version, in one transaction: portal visitors see it right away. A form field whose regular expression could hang validation answers 422 `UNSAFE_FIELD_PATTERN`." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PortalBuilderPublishRequest" responses: "201": description: Version published, with the draft’s new `revision`. content: application/json: schema: $ref: "#/components/schemas/PortalBuilderPublishResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: "The `revision` sent is stale: someone (or another tab) saved the draft in between. Read it again and resend." content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: A form field regular expression could hang validation (`UNSAFE_FIELD_PATTERN`); `details` names the page, block and field. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-portal-builder-publish parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/portal_builder/versions/{number}: get: tags: - Portal Builder summary: Get a published version description: Returns a published version of the portal, by number, with the pages it froze. security: - bearerAuth: [] parameters: - schema: type: string description: Published version number (`1`, `2`…). example: "3" required: true name: number in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: The version and its pages. content: application/json: schema: $ref: "#/components/schemas/PortalVersionDetailResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-portal-builder-versions-number /v1/portal_builder/versions/{number}/rollback: post: tags: - Portal Builder summary: Roll back to a version description: Puts that version back on the air as the next number — portal visitors see it right away. Returns the new version and the builder as it now stands. security: - bearerAuth: [] parameters: - schema: type: string description: Published version number (`1`, `2`…). example: "3" required: true name: number in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "201": description: The new live version and the updated builder. content: application/json: schema: $ref: "#/components/schemas/PortalBuilderRollbackResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: That version is already live (`ALREADY_LIVE`). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-portal-builder-versions-number-rollback /v1/portal_builder/secrets: post: tags: - Portal Builder summary: Seal a block secret description: "Encrypts a value a block keeps in the page JSON (a webhook header such as `Authorization`). Returns `secret:`, bound to this workspace and to the origin of `url` (required), which only the server opens to send the request to that origin. Nothing is stored: save the returned value in the block with the draft." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PortalBuilderSecretRequest" responses: "200": description: The sealed value. content: application/json: schema: $ref: "#/components/schemas/PortalBuilderSecretResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: The `url` has no fixed http(s) origin — e.g. a `{{variable}}` in the host (`ACTION_SECRET_URL_REQUIRED`). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-portal-builder-secrets parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/portal_builder/og_image: post: tags: - Portal Builder summary: Upload an og:image description: Uploads a page's (or the SEO defaults') og:image — the picture link previews show — and returns its public URL, to store in `seo.og_image_url` (or `seo_defaults.og_image_url`) with the next draft save. PNG, JPEG or WebP, base64-encoded; up to 2 MB of image, but the whole request body is capped at 2 MB (about 1.5 MB of image once encoded). security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PortalBuilderOgImageRequest" responses: "201": description: Image uploaded, with its public URL. content: application/json: schema: $ref: "#/components/schemas/PortalBuilderOgImageResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "413": description: The request body exceeds 2 MB. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Type not accepted, invalid base64, image over the limit, or bytes that do not match `content_type`. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-portal-builder-og-image parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/portal_builder/form_submissions: post: tags: - Portal Builder summary: Test a draft form description: "Runs a Form block's action the way the builder's preview does: the configured e-mail really goes out (or the chosen webhook really fires), marked `preview: true`. The form configuration comes in the body. The test e-mail goes only to the e-mail of the token's operator (a token without one cannot test the e-mail action). Capped at 20 runs a minute per operator, 60 a minute and 500 a day per organization, sharing the budget with the dashboard preview." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PortalBuilderFormSubmissionRequest" responses: "200": description: "Submission recorded: recipients, notifications or the webhook delivery." content: application/json: schema: $ref: "#/components/schemas/PortalBuilderFormSubmissionResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Values failing the form rules, an unsafe regular expression or a misconfigured action; `field_errors` lists the fields. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-portal-builder-form-submissions parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/portal_builder/action_runs: post: tags: - Portal Builder summary: Test a draft action button description: "Runs an Action button's webhook the way the builder's preview does: the request really goes out, marked `preview: true`, and the answer carries the HTTP status the target replied with. Headers may carry `secret:` values sealed by `POST /portal_builder/secrets`, which open only for the origin they were sealed for. Capped at 20 runs a minute per operator, 60 a minute and 500 a day per organization." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PortalBuilderActionRunRequest" responses: "200": description: The run result. content: application/json: schema: $ref: "#/components/schemas/PortalBuilderActionRunResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Misconfigured request (URL without https, invalid header, a secret from another workspace…). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-portal-builder-action-runs parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/portal_settings: get: tags: - Portal Settings summary: Get portal settings description: "Returns the workspace portal's configuration: branding, page language, colors, address, login and SSO options, notifications and sender, and site settings (security headers, SEO, trackers, chat and custom code)." security: - bearerAuth: [] responses: "200": description: The workspace portal's configuration, with defaults applied. content: application/json: schema: $ref: "#/components/schemas/PortalSettingsResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-portal-settings parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier patch: tags: - Portal Settings summary: Update portal settings description: "Updates the workspace portal's configuration. Partial: only the fields sent change. Returns the full configuration." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PortalSettingsUpdateRequest" responses: "200": description: The workspace portal's configuration, with defaults applied. content: application/json: schema: $ref: "#/components/schemas/PortalSettingsResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Refused by a business rule (address taken or reserved, file too large or of an unaccepted type…). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-portal-settings parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/portal_settings/logo: post: tags: - Portal Settings summary: Upload portal image description: Uploads the portal's logo, dark-background logo or favicon, as base64 in the JSON body. Replaces the previous image. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PortalLogoUploadRequest" responses: "201": description: Image saved; `url` is its public address. content: application/json: schema: $ref: "#/components/schemas/PortalLogoUploadResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Refused by a business rule (address taken or reserved, file too large or of an unaccepted type…). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-portal-settings-logo parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier delete: tags: - Portal Settings summary: Delete portal image description: Removes the logo, dark-background logo or favicon; the portal falls back to its default. security: - bearerAuth: [] parameters: - schema: type: string enum: - logo - logo_light - favicon description: "Which image: `logo` (default), `logo_light` (logo for dark backgrounds) or `favicon`." required: false name: variant in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Image removed. content: application/json: schema: $ref: "#/components/schemas/PortalLogoDeleteResponse" "400": description: Invalid request (missing or malformed parameter). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-portal-settings-logo /v1/portal_settings/domain: patch: tags: - Portal Settings summary: Set portal address description: Sets the portal's platform address, `https://{slug}.{domain}`, or removes it when both are `null`. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PortalDomainUpdateRequest" responses: "200": description: Address updated. content: application/json: schema: $ref: "#/components/schemas/PortalDomainResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Refused by a business rule (address taken or reserved, file too large or of an unaccepted type…). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-portal-settings-domain parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/portal_settings/domain/check_slug: get: tags: - Portal Settings summary: Check address availability description: Tells whether `slug.domain` is free for this workspace's portal (its own current address counts as free). security: - bearerAuth: [] parameters: - schema: type: string description: "Subdomain: 3 to 50 lowercase letters, digits and hyphens (no hyphen at either end). `null` to remove." example: acme required: true name: slug in: query - schema: type: string description: One of the platform domains (`available_domains`). `null` to remove. required: true name: domain in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Result of the check. content: application/json: schema: $ref: "#/components/schemas/PortalSlugCheckResponse" "400": description: Invalid request (missing or malformed parameter). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-portal-settings-domain-check-slug /v1/portal_settings/sender_identity: post: tags: - Portal Settings summary: Verify notification sender description: Requests or checks the sender verification on AWS SES. When the address was never submitted to SES or its verification failed, SES e-mails it a confirmation link; otherwise the current state is polled. security: - bearerAuth: [] responses: "200": description: Verification status. content: application/json: schema: $ref: "#/components/schemas/PortalSenderIdentityResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-portal-settings-sender-identity parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/portal_custom_domains: get: tags: - Portal Custom Domains summary: List custom domains description: Lists the custom domains of the workspace's portal (the whole set, unpaginated). Empty where custom domains are not supported. security: - bearerAuth: [] responses: "200": description: The portal's custom domains. content: application/json: schema: $ref: "#/components/schemas/PortalCustomDomainListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-portal-custom-domains parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier post: tags: - Portal Custom Domains summary: Add custom domain description: "Registers a custom domain as `pending_verification`, without touching AWS, and returns the DNS records to publish. Then call `POST /portal_custom_domains/{id}/verify`. Registering is only a claim: the domain goes to the first portal that publishes its verification TXT (the other unproven claims are released), and an unproven claim expires after 7 days. A portal holds at most 10 domains. Platform domains (`kobana.com.br`, `kobana.tech` and the shared portal domains) are refused. 403 where custom domains are not available." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PortalCustomDomainCreateRequest" responses: "201": description: The custom domain. content: application/json: schema: $ref: "#/components/schemas/PortalCustomDomainResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: This domain is already registered (proven by another portal, or already claimed by this one). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Reserved platform domain (`hostname_reserved`) or the portal reached its domain limit (`domain_limit_reached`). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-portal-custom-domains parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/portal_custom_domains/{id}: delete: tags: - Portal Custom Domains summary: Delete custom domain description: Removes the custom domain and tears down its CloudFront tenant and certificate when provisioned. The portal stops answering on that hostname. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Custom domain id. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Removed. content: application/json: schema: $ref: "#/components/schemas/PortalSettingsDeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-portal-custom-domains-id /v1/portal_custom_domains/{id}/verify: post: tags: - Portal Custom Domains summary: Verify and provision custom domain description: While pending, checks the DNS and provisions the domain on AWS (certificate and CloudFront tenant); once provisioned, refreshes its status. Returns the domain with its new `status`. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Custom domain id. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: The custom domain. content: application/json: schema: $ref: "#/components/schemas/PortalCustomDomainResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-portal-custom-domains-id-verify /v1/portal_custom_domains/{id}/dns_status: get: tags: - Portal Custom Domains summary: Check custom domain DNS description: Read-only lookup of the required CNAMEs, record by record, without changing anything on AWS. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Custom domain id. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: DNS status. content: application/json: schema: $ref: "#/components/schemas/PortalCustomDomainDnsStatusResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-portal-custom-domains-id-dns-status /v1/portal_oauth_providers: get: tags: - Portal OIDC Providers summary: List OIDC providers description: Lists the OpenID Connect providers portal users can sign in with (the whole set, unpaginated). security: - bearerAuth: [] responses: "200": description: The portal's OIDC providers. content: application/json: schema: $ref: "#/components/schemas/PortalOAuthProviderListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-portal-oauth-providers parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier post: tags: - Portal OIDC Providers summary: Add OIDC provider description: Adds an OpenID Connect provider to the portal login. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PortalOAuthProviderCreateRequest" responses: "201": description: The provider (without the secret). content: application/json: schema: $ref: "#/components/schemas/PortalOAuthProviderResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-portal-oauth-providers parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/portal_oauth_providers/{id}: patch: tags: - Portal OIDC Providers summary: Update OIDC provider description: "Updates an OpenID Connect provider. Partial: only the fields sent change." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: OIDC provider id. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `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: The provider (without the secret). content: application/json: schema: $ref: "#/components/schemas/PortalOAuthProviderResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-portal-oauth-providers-id delete: tags: - Portal OIDC Providers summary: Delete OIDC provider description: Removes the provider; its button leaves the login page and nobody can sign in through it anymore. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: OIDC provider id. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Removed. content: application/json: schema: $ref: "#/components/schemas/PortalSettingsDeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-portal-oauth-providers-id /v1/portal_oauth_providers/test: post: tags: - Portal OIDC Providers summary: Test OIDC issuer description: "Fetches the issuer's discovery document and reports its endpoints, to validate the URL before saving. A discovery failure is a 200 with `ok: false`." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PortalOAuthProviderTestRequest" responses: "200": description: Result of the test. content: application/json: schema: $ref: "#/components/schemas/PortalOAuthProviderTestResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-portal-oauth-providers-test parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/webhooks: get: tags: - Webhooks summary: List webhook endpoints description: Lists the webhook endpoints of the workspace, newest first, each with its delivery count. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string enum: - active - inactive description: "`active` or `inactive`." required: false name: status in: query - schema: type: string description: Substring of the URL or the description, case-insensitive. required: false name: search in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: A page of webhook endpoints. content: application/json: schema: $ref: "#/components/schemas/WebhookListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-webhooks post: tags: - Webhooks summary: Create a webhook endpoint description: Creates an active endpoint in the workspace. The response carries the signing `secret` — it only appears here (and on rotation). security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/WebhookCreateRequest" responses: "201": description: Endpoint created, with its signing secret. content: application/json: schema: $ref: "#/components/schemas/WebhookWithSecretResponse" "400": description: "Bad request: malformed body, missing required field or a filter with an invalid value." content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-webhooks parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/webhooks/{id}: get: tags: - Webhooks summary: Get a webhook endpoint description: Returns one webhook endpoint of the workspace. Its deliveries are at `GET /webhooks/{id}/deliveries`. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Webhook endpoint ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: The webhook endpoint. content: application/json: schema: $ref: "#/components/schemas/WebhookResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-webhooks-id patch: tags: - Webhooks summary: Update a webhook endpoint description: Changes the URL, description, subscribed events, `active` or the authentication. Absent fields are left as they are. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Webhook endpoint ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `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 updated. content: application/json: schema: $ref: "#/components/schemas/WebhookResponse" "400": description: "Bad request: malformed body, missing required field or a filter with an invalid value." content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-webhooks-id delete: tags: - Webhooks summary: Delete a webhook endpoint description: Deletes the endpoint for good, together with its delivery log. Events stop being sent immediately. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Webhook endpoint ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Endpoint deleted. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-webhooks-id /v1/webhooks/{id}/test: post: tags: - Webhooks summary: Send a test webhook description: "Sends a signed `test.webhook` event to the endpoint URL now and records it in the delivery log. Answers 200 with `success: false` when the endpoint answers non-2xx or cannot be reached, and 422 when the URL points to a blocked (private network) address." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Webhook endpoint ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Outcome of the attempt. content: application/json: schema: $ref: "#/components/schemas/WebhookTestResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-webhooks-id-test /v1/webhooks/{id}/rotate_secret: post: tags: - Webhooks summary: Rotate the webhook secret description: Generates a new signing secret. The previous one stops working immediately; the new `secret` only appears in this response. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Webhook endpoint ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Endpoint with its new secret. content: application/json: schema: $ref: "#/components/schemas/WebhookWithSecretResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-webhooks-id-rotate-secret /v1/webhooks/{id}/deliveries: get: tags: - Webhooks summary: List the deliveries of a webhook description: Delivery log of one endpoint, newest first. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Webhook endpoint ID (UUID). required: true name: id in: path - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string enum: - pending - delivered - failed description: "`pending`, `delivered` or `failed`." required: false name: status in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: A page of deliveries. content: application/json: schema: $ref: "#/components/schemas/WebhookDeliveryListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-webhooks-id-deliveries /v1/webhooks/{id}/deliveries/{delivery_id}/retry: post: tags: - Webhooks summary: Retry a webhook delivery description: "Puts the delivery back to `pending` and queues it to be sent again. Sending is asynchronous: follow the outcome in the delivery log." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Webhook endpoint ID (UUID). required: true name: id in: path - schema: type: string format: uuid description: Delivery ID (UUID), from the delivery log. required: true name: delivery_id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "202": description: Delivery queued to be sent again. content: application/json: schema: $ref: "#/components/schemas/WebhookDeliveryRetryResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-webhooks-id-deliveries-delivery-id-retry /v1/webhook_deliveries: get: tags: - Webhooks summary: List webhook deliveries description: Deliveries of every endpoint of the workspace, newest first, with the event type and an endpoint summary. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string enum: - pending - delivered - failed description: "`pending`, `delivered` or `failed`." required: false name: status in: query - schema: type: string format: uuid description: Only deliveries of this webhook endpoint. required: false name: webhook_id in: query - schema: type: string description: Lower bound of `created_at` (ISO 8601 date or date-time). required: false name: date_from in: query - schema: type: string description: Upper bound of `created_at` (ISO 8601 date or date-time). A bare date covers the whole day (UTC). required: false name: date_to in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: A page of deliveries. content: application/json: schema: $ref: "#/components/schemas/WebhookDeliveryListResponse" "400": description: "Bad request: malformed body, missing required field or a filter with an invalid value." content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-webhook-deliveries /v1/webhook_deliveries/{id}: get: tags: - Webhooks summary: Get a webhook delivery description: "Returns one delivery: the (redacted) request, the response, attempts and the target endpoint." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Delivery ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: The delivery. content: application/json: schema: $ref: "#/components/schemas/WebhookDeliveryResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-webhook-deliveries-id /v1/events: get: tags: - Events summary: List events description: "Event log of the workspace and of the organization, newest first. Events are evidence: they cannot be changed or deleted." security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string description: Exact event type (e.g. `api_key.rotated`). required: false name: type in: query - schema: type: string description: Exact resource type (e.g. `api_key`). required: false name: resource_type in: query - schema: type: string format: uuid description: Only events about this record. required: false name: resource_id in: query - schema: type: string description: Lower bound of `created_at` (ISO 8601 date or date-time). required: false name: date_from in: query - schema: type: string description: Upper bound of `created_at` (ISO 8601 date or date-time). A bare date covers the whole day (UTC). required: false name: date_to in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: A page of events. content: application/json: schema: $ref: "#/components/schemas/EventListResponse" "400": description: "Bad request: malformed body, missing required field or a filter with an invalid value." content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-events /v1/events/{id}: get: tags: - Events summary: Get an event description: Returns one event with its full payload. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Event ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: The event. content: application/json: schema: $ref: "#/components/schemas/EventResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-events-id /v1/audit_logs: get: tags: - Audit Logs summary: List audit logs description: Audit trail of the workspace and of the organization, newest first. The trail cannot be changed. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string description: Exact user identifier. required: false name: user_id in: query - schema: type: string description: Exact action (e.g. `webhook.created`). required: false name: action in: query - schema: type: string description: Exact resource type (e.g. `webhook`). required: false name: resource_type in: query - schema: type: string description: Exact resource ID. required: false name: resource_id in: query - schema: type: string description: Substring of the action, resource type, user ID or user e-mail, case-insensitive. required: false name: search in: query - schema: type: string description: Lower bound of `created_at` (ISO 8601 date or date-time). required: false name: date_from in: query - schema: type: string description: Upper bound of `created_at` (ISO 8601 date or date-time). A bare date covers the whole day (UTC). required: false name: date_to in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: A page of audit entries. content: application/json: schema: $ref: "#/components/schemas/AuditLogListResponse" "400": description: "Bad request: malformed body, missing required field or a filter with an invalid value." content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-audit-logs /v1/audit_logs/summary: get: tags: - Audit Logs summary: Audit activity summary description: "Activity of the last `hours` hours: total entries, the 10 most frequent actions and the 20 most recent entries. Requires the audit export permission." security: - bearerAuth: [] parameters: - schema: type: number minimum: 1 maximum: 8760 description: Window size in hours, 1 to 8760. Default 24. example: 24 required: false name: hours in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Activity summary. content: application/json: schema: $ref: "#/components/schemas/AuditLogSummaryResponse" "400": description: "Bad request: malformed body, missing required field or a filter with an invalid value." content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-audit-logs-summary /v1/audit_logs/{id}: get: tags: - Audit Logs summary: Get an audit log description: Returns one audit entry with its previous and new values. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Audit entry ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: The audit entry. content: application/json: schema: $ref: "#/components/schemas/AuditLogResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-audit-logs-id /v1/email_templates: get: tags: - Email Templates summary: List email templates description: Lists the organization's own email templates, ordered by type and name. Returns the whole set, unpaginated. 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: Only templates of this notification type. required: false name: type in: query - schema: type: string enum: - "true" - "false" description: "`true` for the active templates, `false` for the drafts." required: false name: is_active in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: The organization's templates. content: application/json: schema: $ref: "#/components/schemas/EmailTemplateListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-email-templates post: tags: - Email Templates summary: Create email template description: Creates a template for a notification type. It is a draft unless `is_active` is `true` — then the previous active template of the type becomes a draft. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/EmailTemplateCreateRequest" responses: "201": description: Template created. content: application/json: schema: $ref: "#/components/schemas/EmailTemplateResponse" "400": description: Invalid request (missing required field, invalid type or variables). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-email-templates parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/email_templates/init_defaults: post: tags: - Email Templates summary: Reset templates to defaults description: Creates or resets the template of every notification type to the shipped default and activates it. Overwrites the content of the organization's existing templates. security: - bearerAuth: [] responses: "200": description: One row per notification type. content: application/json: schema: $ref: "#/components/schemas/EmailTemplateDefaultsResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-email-templates-init-defaults parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/email_templates/{id}: get: tags: - Email Templates summary: Get email template description: Returns a template of the organization or a platform default. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Template ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: The template. content: application/json: schema: $ref: "#/components/schemas/EmailTemplateResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-email-templates-id patch: tags: - Email Templates summary: Update email template description: Updates a template of the organization. Only the fields sent change. Platform defaults cannot be changed (404). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Template ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `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: Template updated. content: application/json: schema: $ref: "#/components/schemas/EmailTemplateResponse" "400": description: Invalid request (missing required field, invalid type or variables). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: The `public_id` sent is already in use. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-email-templates-id delete: tags: - Email Templates summary: Delete email template description: "Permanently deletes an inactive template of the organization. The active template of a type cannot be deleted (422): activate another one first." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Template ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Template deleted. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-email-templates-id /v1/email_templates/{id}/duplicate: post: tags: - Email Templates summary: Duplicate email template description: Copies a template as an inactive draft. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Template ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `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: The copy created. content: application/json: schema: $ref: "#/components/schemas/EmailTemplateResponse" "400": description: Invalid request (missing required field, invalid type or variables). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-email-templates-id-duplicate /v1/email_templates/{id}/preview: get: tags: - Email Templates summary: Preview email template description: Renders the template with sample data, inside the organization's layout. Nothing is sent. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Template ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: The rendered email. content: application/json: schema: $ref: "#/components/schemas/EmailTemplateRenderResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-email-templates-id-preview post: tags: - Email Templates summary: Render template with variables description: Renders the template with the `variables` sent, without a layout. Nothing is sent. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Template ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `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: The rendered email. content: application/json: schema: $ref: "#/components/schemas/EmailTemplateRenderResponse" "400": description: Invalid request (missing required field, invalid type or variables). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-email-templates-id-preview /v1/email_layouts: get: tags: - Email Layouts summary: List email layouts description: Lists the organization's email layouts, default first. Returns the whole set, unpaginated. security: - bearerAuth: [] responses: "200": description: The organization's layouts. content: application/json: schema: $ref: "#/components/schemas/EmailLayoutListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-email-layouts parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier post: tags: - Email Layouts summary: Create email layout description: Creates a layout. The HTML must contain the `{{content}}` placeholder. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/EmailLayoutCreateRequest" responses: "201": description: Layout created. content: application/json: schema: $ref: "#/components/schemas/EmailLayoutResponse" "400": description: Invalid request (missing required field, invalid type or variables). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-email-layouts parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/email_layouts/init_defaults: post: tags: - Email Layouts summary: Create default layout description: "Makes sure the organization has a default layout: returns the current one or creates the built-in one. Never overwrites a layout." security: - bearerAuth: [] responses: "200": description: The default layout. content: application/json: schema: $ref: "#/components/schemas/EmailLayoutResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-email-layouts-init-defaults parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/email_layouts/{id}: get: tags: - Email Layouts summary: Get email layout description: Returns a layout of the organization. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Layout ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: The layout. content: application/json: schema: $ref: "#/components/schemas/EmailLayoutResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-email-layouts-id patch: tags: - Email Layouts summary: Update email layout description: Updates the name, HTML (which must keep `{{content}}`), default or active flag. Only the fields sent change. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Layout ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `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 updated. content: application/json: schema: $ref: "#/components/schemas/EmailLayoutResponse" "400": description: Invalid request (missing required field, invalid type or variables). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-email-layouts-id delete: tags: - Email Layouts summary: Delete email layout description: Permanently deletes a layout. Emails fall back to the default layout (or the built-in one). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Layout ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Layout deleted. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-email-layouts-id /v1/notifications: get: tags: - Notifications summary: List notifications description: Lists the notifications of the workspace and the organization-wide ones, newest first. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `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: Only this notification type. required: false name: type in: query - schema: type: string enum: - email - in_app - webhook description: Only this channel. required: false name: channel in: query - schema: type: string enum: - pending - sent - delivered - failed - read - skipped description: Only this status. required: false name: status in: query - schema: type: string description: Start of creation date range (YYYY-MM-DD). required: false name: created_after in: query - schema: type: string description: End of creation date range (YYYY-MM-DD). required: false name: created_before in: query - schema: type: string description: Substring of the recipient or the subject, case-insensitive. required: false name: search in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Page of notifications. content: application/json: schema: $ref: "#/components/schemas/NotificationListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-notifications post: tags: - Notifications summary: Create notification description: Renders the active template of the type with the variables, stores the notification and sends it right away — the response carries the outcome (`sent`, or `failed` with `failure_reason`). With a future `scheduled_for` it stays `pending` until it is due. Every creation counts toward the per-recipient manual-send limit (429). security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/NotificationCreateRequest" responses: "201": description: Notification created. content: application/json: schema: $ref: "#/components/schemas/NotificationResponse" "400": description: Invalid request (missing required field, invalid type or variables). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-notifications parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/notifications/stats: get: tags: - Notifications summary: Notification statistics description: Counts by status, type and channel of the notifications created in the last `days` days, with the delivery and read rates. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 maximum: 365 description: Window in days, 1 to 365. Default 30. example: 30 required: false name: days in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: The statistics. content: application/json: schema: $ref: "#/components/schemas/NotificationStatsResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-notifications-stats /v1/notifications/{id}/send: post: tags: - Notifications summary: Send notification description: "Sends a stored notification now: the first send of a `pending` (scheduled) or `skipped` one, or a resend of a `sent`, `delivered`, `read` or `failed` one. Every call sends the email again and counts toward the per-recipient manual-send limit (429)." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Notification ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: The updated notification. content: application/json: schema: $ref: "#/components/schemas/NotificationSendResponse" "400": description: Invalid request (missing required field, invalid type or variables). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "502": description: The email provider refused the send; the reason is in the message. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-notifications-id-send /v1/api_keys: get: tags: - API Keys summary: List API keys description: "Lists the organization API keys (`kb_…`), without the secret. These keys no longer authenticate the API v1 nor the MCP — both take access tokens issued by the Kobana authorization server; the records remain the organization key inventory (lifecycle, expiry reminders and `api_key.*` webhooks). Organization-level: ignores `X-Workspace-Id`." security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string enum: - active - disabled - revoked description: "Filter by status: `active`, `disabled` or `revoked`." required: false name: status in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Page of API keys. content: application/json: schema: $ref: "#/components/schemas/ApiKeyListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-api-keys post: tags: - API Keys summary: Create API key description: Creates an active key, valid for one year unless `expires_at` says otherwise. The secret (`key`) is returned ONCE in this response — only its hash is stored. Requires a person who reaches every workspace (organization owner or granted on each one), as in the dashboard. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ApiKeyCreateRequest" responses: "201": description: Key created, with the secret in `key` (shown only now). content: application/json: schema: $ref: "#/components/schemas/ApiKeyCreatedResponse" "400": description: Missing body, invalid JSON or incompatible fields. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-api-keys parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/api_keys/{id}: get: tags: - API Keys summary: Get API key description: Returns one organization key — metadata and lifecycle stamps, never the secret. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: API key ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: The API key. content: application/json: schema: $ref: "#/components/schemas/ApiKeyResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-api-keys-id patch: tags: - API Keys summary: Update API key description: Edits name, description, source, notification e-mails and expiry, and/or enables ⇄ disables the key with `enabled`. A revoked key is terminal (409). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: API key ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `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: The API key. content: application/json: schema: $ref: "#/components/schemas/ApiKeyResponse" "400": description: Missing body, invalid JSON or incompatible fields. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: The current state of the resource does not allow this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-api-keys-id delete: tags: - API Keys summary: Remove revoked API key description: Removes an ALREADY REVOKED key from the list (soft delete; history is kept). An active or disabled key must be revoked first (409). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: API key ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Removed. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: The current state of the resource does not allow this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-api-keys-id /v1/api_keys/{id}/revoke: post: tags: - API Keys summary: Revoke API key description: Permanently revokes the key — it cannot be re-enabled. 409 when it is already revoked. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: API key ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: The API key. content: application/json: schema: $ref: "#/components/schemas/ApiKeyResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: The current state of the resource does not allow this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-api-keys-id-revoke /v1/api_keys/{id}/rotate: post: tags: - API Keys summary: Rotate API key description: Issues a successor key (same name and settings) and keeps the previous one working for `grace_days` days (default 7, max 30). Only an active key rotates (409). The new secret is returned ONCE. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: API key ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `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: The successor key with its secret in `key`, and `previous_key` with the grace period of the old one. content: application/json: schema: $ref: "#/components/schemas/ApiKeyRotatedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: The current state of the resource does not allow this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-api-keys-id-rotate /v1/exports: get: tags: - Exports summary: List exports description: Lists the export requests of the workspace. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string description: Exported resource, e.g. `portal_users`. required: false name: resource_type in: query - schema: type: string enum: - pending - processing - completed - failed description: Filter by export status. required: false name: status in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Page of exports. content: application/json: schema: $ref: "#/components/schemas/ExportListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-exports post: tags: - Exports summary: Request export description: "Queues an export of the workspace portal users as CSV, XLSX or JSON. Asynchronous: answers 202 with the `pending` export; poll `GET /exports/{id}` until `completed` and download from `/download`. The file expires after 7 days." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ExportCreateRequest" responses: "202": description: Export queued. content: application/json: schema: $ref: "#/components/schemas/ExportResponse" "400": description: Missing body, invalid JSON or incompatible fields. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-exports parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/exports/{id}: get: tags: - Exports summary: Get export description: Status and metadata of one export request. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Export ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: The export. content: application/json: schema: $ref: "#/components/schemas/ExportResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-exports-id /v1/exports/{id}/download: get: tags: - Exports summary: Download export file description: Returns the file of a completed export (the dashboard redirects to a signed URL; the API serves the bytes). 404 while it is not ready. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Export ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: The file, as an attachment. 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: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-exports-id-download /v1/imports: get: tags: - Imports summary: List imports description: Lists the import requests of the workspace, with success and error counters. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string description: Imported resource, e.g. `portal_users`. required: false name: resource_type in: query - schema: type: string enum: - pending - processing - completed - completed_with_errors - failed description: Filter by import status. required: false name: status in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Page of imports. content: application/json: schema: $ref: "#/components/schemas/ImportListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-imports post: tags: - Imports summary: Import CSV description: 'Sends a base64 CSV and queues the import of portal users into the workspace. The dashboard uploads the file first; the API takes it in the body (2 MB request limit). Follows the organization setting "allow creating portal users" (403 when off). Asynchronous: 202; poll `GET /imports/{id}`.' security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ImportCreateRequest" responses: "202": description: Import queued. content: application/json: schema: $ref: "#/components/schemas/ImportResponse" "400": description: Missing body, invalid JSON or incompatible fields. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-imports parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/imports/{id}: get: tags: - Imports summary: Get import description: Status, counters and per-row errors of an import. An import still `pending` 2 minutes after the request is shown as `failed` (stalled queue); the read does not change the record. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Import ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: The import. content: application/json: schema: $ref: "#/components/schemas/ImportResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-imports-id /v1/backups: get: tags: - Backups summary: List backups description: Lists the organization backups and restores (metadata only) and whether a new backup may be requested now (`backup_allowed`, `next_backup_at` — one every 12 hours in production). Organization-level. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string enum: - backup - restore description: "`backup` or `restore`." required: false name: type in: query - schema: type: string enum: - pending - processing - completed - failed - canceled description: Filter by status. required: false name: status in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Page of backups. content: application/json: schema: $ref: "#/components/schemas/BackupListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-backups post: tags: - Backups summary: Request backup description: "Queues a full backup (ZIP) of the organization, every workspace included. Asynchronous: 202; poll `GET /backups/{id}`." security: - bearerAuth: [] responses: "202": description: Backup queued. content: application/json: schema: $ref: "#/components/schemas/BackupResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Still within the 12-hour interval between backups (`BACKUP_COOLDOWN`, with `next_backup_at`). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-backups parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/backups/restore: post: tags: - Backups summary: Restore backup description: "DESTRUCTIVE: restores a backup into the workspace of the call (`X-Workspace-Id`), rewriting portal users matched by e-mail/public id. Send `backup_id` (a completed backup of this organization — its file is copied) OR `file_name` (`.zip`) + `content_base64` (bounded by the 2 MB request limit). Requires `settings.update` and access to every workspace. Asynchronous: 202; follow it on `GET /backups/{id}` and cancel with `/cancel`." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/BackupRestoreRequest" responses: "202": description: Restore queued (a `restore` record). content: application/json: schema: $ref: "#/components/schemas/BackupResponse" "400": description: Missing body, invalid JSON or incompatible fields. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-backups-restore parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/backups/{id}: get: tags: - Backups summary: Get backup description: Status and progress of a backup or restore. An in-progress restore whose queue job is gone is marked `failed`. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Backup or restore ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: The backup. content: application/json: schema: $ref: "#/components/schemas/BackupResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-backups-id delete: tags: - Backups summary: Delete backup description: Deletes the record and its file from storage. Permanent. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Backup or restore ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Removed. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-backups-id /v1/backups/{id}/cancel: post: tags: - Backups summary: Cancel restore description: Stops a pending or running restore. What was already restored stays. 422 for a backup or a restore that already ended. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Backup or restore ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: The backup. content: application/json: schema: $ref: "#/components/schemas/BackupResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-backups-id-cancel /v1/backups/{id}/download: get: tags: - Backups summary: Download backup description: Returns the backup ZIP. Requires `backups.export` and, for a person token, being an organization owner or holding access to every workspace — the backup holds all of them. Audited. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Backup or restore ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: The ZIP file. content: application/zip: schema: type: string format: binary "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-backups-id-download /v1/data_purges: get: tags: - Data Purge summary: Count purgeable data description: How many rows each purgeable resource (`portal_users`, `people`, `usage_history`) holds across every workspace. Requires `data.purge` (organization owners only by default) and access to every workspace. security: - bearerAuth: [] responses: "200": description: The counts. content: application/json: schema: $ref: "#/components/schemas/DataPurgeCountsResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-data-purges parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier post: tags: - Data Purge summary: Purge organization data description: "IRREVERSIBLE: permanently deletes the chosen resources in EVERY workspace of the organization. In the dashboard the operation is confirmed with a code sent by e-mail. That is why a token that names a person (a personal or OAuth token, or a call through the MCP) gets 403: the person purges from the dashboard. Only machine tokens can purge over the API, and only when the token carries the dedicated `dashboards/data_purges:write` scope — granted explicitly: no other scope implies it (not `write`, `all`, `dashboards/all` or `dashboards/admin:write`); without it, 403 `insufficient_scope`. Their confirmation is `confirm`, which must repeat the organization id (from `GET /organization`) — a retried or mis-targeted call cannot pass by accident. Requires `data.purge` (organization owners only by default) and access to every workspace. Asynchronous: 202 with `job_id`." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/DataPurgeRequest" responses: "202": description: Purge queued; follow it on `GET /data_purges/{id}`. content: application/json: schema: $ref: "#/components/schemas/DataPurgeQueuedResponse" "400": description: Missing body, invalid JSON or incompatible fields. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: "`confirm` does not match the organization id — nothing was purged." content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-data-purges parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/data_purges/{id}: get: tags: - Data Purge summary: Get purge job description: "Progress and result of a purge job. A job of another organization: 404." security: - bearerAuth: [] parameters: - schema: type: string description: The `job_id` returned by `POST /data_purges`. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: The job. content: application/json: schema: $ref: "#/components/schemas/DataPurgeJobResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-data-purges-id /v1/maintenance/uppercase_names: post: tags: - Maintenance summary: Upper-case contact names description: Upper-cases the name of every contact linked to a portal user of the workspace. Not reversible (the previous spelling is not kept). security: - bearerAuth: [] responses: "200": description: How many names changed. content: application/json: schema: $ref: "#/components/schemas/MaintenanceUppercaseNamesResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-maintenance-uppercase-names parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/settings: get: tags: - Settings summary: Get organization settings description: Name, support e-mail, timezone and the records options of the organization. Organization-level. security: - bearerAuth: [] responses: "200": description: The settings. content: application/json: schema: $ref: "#/components/schemas/OrganizationSettingsResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-settings parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier put: tags: - Settings summary: Update organization settings description: "Partially changes the settings: send only what changes. Unknown fields are refused (400)." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/OrganizationSettingsUpdateRequest" responses: "200": description: The settings. content: application/json: schema: $ref: "#/components/schemas/OrganizationSettingsResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-settings parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/usage: get: tags: - Usage summary: Get platform usage description: "For each metric (members, customers, portal users, integrations…), the daily series in the range, the latest value and the peak. Default: current month; at most 12 months back. Organization-level." security: - bearerAuth: [] parameters: - schema: type: string format: date description: "First day (YYYY-MM-DD). Default: day 1 of the current month." example: 2026-01-15 required: false name: start_date in: query - schema: type: string format: date description: "Last day (YYYY-MM-DD). Default: today." example: 2026-01-15 required: false name: end_date in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: The usage. content: application/json: schema: $ref: "#/components/schemas/SystemUsageResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-usage /v1/ai_usage: get: tags: - AI Usage summary: Get AI usage description: "AI consumption, price only (cost and margin never leave): totals, daily breakdown and latest turns of the workspace of the call, plus the month to date, grants, limits, credit balance and whether the next turn is allowed — those for the whole organization, as the limit and the credit are shared. Default period: current month (America/Sao_Paulo), at most 366 days." security: - bearerAuth: [] parameters: - schema: type: string format: date description: First day (YYYY-MM-DD). example: 2026-01-15 required: false name: start_date in: query - schema: type: string format: date description: Last day (YYYY-MM-DD). example: 2026-01-15 required: false name: end_date in: query - schema: type: integer minimum: 1 maximum: 366 description: The last N days, instead of a date range. required: false name: days in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: The AI usage. content: application/json: schema: $ref: "#/components/schemas/AiUsageResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-ai-usage /v1/rate_limits: get: tags: - Rate Limits summary: Get rate limits description: The rate limits in force for the organization, whether they are custom (set by the Kobana team) and the platform defaults. Read-only. security: - bearerAuth: [] responses: "200": description: The limits. content: application/json: schema: $ref: "#/components/schemas/RateLimitsResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-rate-limits parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/portal_user_mappings: get: tags: - Portal Users summary: Get portal user mapping description: The entity that feeds the workspace portal users (`mapping`, `null` when none, with the last sync outcome) and the entities that can be mapped, with their fields. security: - bearerAuth: [] responses: "200": description: The mapping. content: application/json: schema: $ref: "#/components/schemas/PortalUserMappingGetResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-portal-user-mappings parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier put: tags: - Portal Users summary: Map entity to portal users description: "Maps an entity: one portal user per e-mail of its records, with the tenant ID taken from a field. Replaces the previous mapping and syncs right away (returns `stats`); later syncs of the entity keep the users current." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PortalUserMappingUpdateRequest" responses: "200": description: The saved mapping and the sync outcome. content: application/json: schema: $ref: "#/components/schemas/PortalUserMappingUpdateResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Invalid entity or field (e.g. an entity that syncs on access). content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-portal-user-mappings parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier delete: tags: - Portal Users summary: Remove portal user mapping description: Stops syncing; users already created stay. security: - bearerAuth: [] responses: "200": description: "Mapping removed (`deleted: false` when there was none)." content: application/json: schema: $ref: "#/components/schemas/PortalUserMappingDeleteResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-portal-user-mappings parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/assets: get: tags: - Assets summary: List assets description: The file library of the workspace — images and documents the portal shows or offers for download. Sortable by `created_at` (default), `name` or `size_bytes`. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string enum: - image - document - other description: "Filter by kind: `image`, `document` or `other`." required: false name: kind in: query - schema: type: string enum: - public - restricted - private description: "Who may download it: `public` (anyone with the link), `restricted` (users signed in to the workspace portal) or `private` (dashboard members only). New files start `restricted`." required: false name: visibility in: query - schema: type: string description: Part of the file name (case-insensitive). required: false name: search in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Paginated list of assets. content: application/json: schema: $ref: "#/components/schemas/AssetListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-assets post: tags: - Assets summary: Create asset description: "Records a file in the library, one of two ways: the `key` of a file already sent through the URL of `POST /assets/presign`, or the content itself in `content_base64`. The file starts `restricted` unless `visibility` says otherwise. Fires the `asset.created` webhook." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/AssetCreateRequest" responses: "201": description: Asset recorded. content: application/json: schema: $ref: "#/components/schemas/AssetResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-assets parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/assets/presign: post: tags: - Assets summary: Get an upload URL description: A short-lived signed URL to send the file straight to storage with `PUT` — the way for files over the 2 MB body limit. After the `PUT`, record the file at `POST /assets` with the returned `key`. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/AssetPresignRequest" responses: "200": description: Upload URL issued. content: application/json: schema: $ref: "#/components/schemas/AssetPresignResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-assets-presign parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier /v1/assets/{id}: get: tags: - Assets summary: Get asset description: One file of the library, with its link, visibility, type and size. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Asset ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: The asset. content: application/json: schema: $ref: "#/components/schemas/AssetResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-assets-id patch: tags: - Assets summary: Update asset description: Renames the file, changes its alternative text or its visibility. Making it public opens its storage URL to anyone; `restricted` or `private` closes it. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Asset ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `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: Asset updated. content: application/json: schema: $ref: "#/components/schemas/AssetResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-assets-id delete: tags: - Assets summary: Delete asset description: Removes the file from the library. The stored file stays in storage, so links already published do not break. Fires the `asset.deleted` webhook. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Asset ID (UUID). required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: Asset deleted. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-assets-id /v1/assets/{id}/download: get: tags: - Assets summary: Download asset description: The file content, whatever its visibility, with its own `Content-Type`. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Asset ID (UUID). required: true name: id in: path - schema: type: string enum: - "true" - "false" description: "With `true`, images and PDF come for display in place (`Content-Disposition: inline`); other types always come as an attachment." required: false name: inline in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid - name: X-Request-Source in: header required: false description: "Surface making the call: `dashboard`, `api`, `cli`, `mcp` or `other`. Stored in `created_via` / `updated_via` of the records it creates or changes. Without the header, `api` is assumed. An unknown value returns 400." schema: type: string enum: - dashboard - api - cli - mcp - other default: api - name: X-Workspace-Id in: header required: false description: "Workspace the call acts on: the `id` or the `public_id` shown under Workspaces on the dashboard. Inside the token's organization, data lives in workspaces. It may be omitted while the organization has a single workspace; with two or more, leaving it out returns `400 workspace_required`. A workspace outside the organization returns `403 unknown_workspace`. With a person token, only the workspaces that person has access to are reachable (organization owners reach all of them); any other returns `403 workspace_access_denied`." schema: type: string format: uuid - name: X-Request-Source-Other in: header required: false description: Name of the app making the call. Required when `X-Request-Source` is `other` (up to 100 characters); ignored otherwise. Stored in `created_via_other` / `updated_via_other`. schema: type: string maxLength: 100 example: Zapier responses: "200": description: The file content. content: application/octet-stream: schema: type: string format: binary "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-assets-id-download webhooks: {}