# Gerado por scripts/generate-openapi-user-docs.ts a partir de public/openapi.json. # Não edite à mão: rode `npm run docs:generate`. openapi: 3.1.0 info: title: API do Kadu version: 1.0.0 description: |- Multi-tenant API for agent orchestration. ## Authentication Every route requires `Authorization: Bearer `, where the token is an RS256 access token issued by Kobana's Authorization Server (Kobana Account) for the `kadu` resource. Kadu only verifies the token, using the public keys the AS publishes; it does not issue tokens. The organization is the `org` claim. ## Scopes Scopes are required on every route, except `GET /v1/me`. Each request requires a single access level, and one level never substitutes for another: | Level | Grants | | --- | --- | | `read` | read (`GET`) | | `write` | create and update (`POST`, `PATCH`, `PUT`) — and read | | `delete` | removal (`DELETE`) | | `import` | bulk import (no endpoint today) | | `export` | bulk export (no endpoint today) | | `all` | all of the levels above | A token with `kadu/{resource}` scopes (e.g. `kadu/tasks`) is restricted to those resources, and the level applies only within them; `kadu/all` reaches every resource. A route's resource is the first segment after `/v1` (`/executions/{id}/logs` → `executions`). Resources: `activities`, `environments`, `executions`, `files`, `memberships`, `memories`, `organizations`, `repository`, `roles`, `schedules`, `secrets`, `system_events`, `tasks`, `todos`, `usage`, `users`, `webhook_deliveries`, `webhooks`, `workspaces`. ## User permissions Besides scopes, a token issued for a person (with `email`) is limited to their role in the organization (`Role.permissions`): each route requires `agent..` (`list`, `read`, `create`, `update`, `delete`, and the actions `executions.run`, `webhook_deliveries.replay` and `repository.sync`), with the wildcards `*`, `agent.*` and `agent..*`. A role that does not grant it responds `403 USER_PERMISSION_DENIED` (`details.required`); a person with no membership in the organization gets `403 NOT_A_MEMBER`. An integration token, with no person, is governed by scopes only. `GET /v1/me` does not check the role. ## Organization permissions The routes for run, logs, webhooks, deliveries, environments, secrets, schedules, Task endpoint, repository and usage also respect the permissions Kobana grants the organization for the console screens. An operation that is not enabled responds `403 FEATURE_NOT_ENABLED`, with `details.permission`. A token with no scope that Kadu recognizes reaches nothing beyond `/me`. Insufficient scope responds `403 INSUFFICIENT_SCOPE`, with `details.required` (the levels that would suffice). ## Contract - Wire in `snake_case`; free-form maps (`custom_metadata`, `payload`, `parameters`…) are opaque. - Monetary and cost values are `number` (USD in `*_usd`, reais in `*_brl`). - Success: `{ data }` or `{ data, meta }`; error: `{ error: { code, message, details? } }` with `code` in UPPER_SNAKE. - Cursor-based listings: `cursor` + `limit` (max. 100), ordering by `sort_by` + `sort_order`; `meta: { next_cursor, limit }`. - `X-Idempotency-Key` on every `POST`/`PUT`/`PATCH` (24h per organization). - `POST`/`PUT`/`PATCH` body up to 1 MiB; above that, `413 PAYLOAD_TOO_LARGE`. servers: - url: https://api.kadu.ia.br description: Production - url: https://api.staging.kadu.ia.br description: Staging components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: "RS256 access token (`typ: at+jwt`) issued by Kobana's Authorization Server (`iss` = `https://account.kobana.com.br`), with `aud` containing `https://api.kadu.ia.br` (staging: `https://api.staging.kadu.ia.br`) and a mandatory `exp`. The organization is the `org` claim (`organizations.public_id`); `sub` is the person. The header must have `typ: at+jwt` (RFC 9068): another JWT from the same issuer, such as an ID token, is rejected. Scopes are required on every route — see the API description." schemas: PaginationMeta: type: object properties: next_cursor: type: - string - "null" limit: type: number required: - next_cursor - limit Error: type: object properties: error: type: object properties: code: type: string description: "Stable UPPER_SNAKE: VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, INSUFFICIENT_SCOPE, NOT_FOUND, CONFLICT, IDEMPOTENCY_KEY_REUSED, IDEMPOTENCY_REQUEST_IN_PROGRESS, RATE_LIMITED, INTERNAL_ERROR, plus the codes specific to each route." example: VALIDATION_ERROR message: type: string details: {} required: - code - message required: - error Organization: type: object properties: id: type: string format: uuid external_id: type: - string - "null" public_id: type: - string - "null" format: uuid label: type: string monthly_cost_limit: type: - number - "null" description: Monthly cost cap in USD, set by Kobana. null = no limit. monthly_cost_accumulated_usd: type: number timezone: type: string custom_metadata: type: object additionalProperties: {} created_at: type: string updated_at: type: string required: - id - external_id - public_id - label - monthly_cost_limit - monthly_cost_accumulated_usd - timezone - custom_metadata - created_at - updated_at Workspace: type: object properties: id: type: string format: uuid label: type: string organization_id: type: string format: uuid created_at: type: string required: - id - label - organization_id - created_at Activity: type: object properties: id: type: string format: uuid label: type: string organization_id: type: string format: uuid workspace_id: type: string format: uuid created_at: type: string required: - id - label - organization_id - workspace_id - created_at Task: type: object properties: id: type: string format: uuid label: type: string skill_slug: type: string organization_id: type: string format: uuid workspace_id: type: string format: uuid activity_id: type: string format: uuid parameters_schema: {} parameters_sensitive: type: boolean conversational: type: boolean description: "Accepts continuing the conversation: `POST /executions/{id}/continue`." required: - id - label - skill_slug - organization_id - workspace_id - activity_id - parameters_sensitive - conversational Execution: type: object properties: id: type: string format: uuid organization_id: type: string format: uuid workspace_id: type: string format: uuid activity_id: type: string format: uuid task_id: type: string format: uuid status: type: string enum: - pending - queued - running - success - failed - cancelled source: type: string reference_date: type: - string - "null" started_at: type: string finished_at: type: - string - "null" cost_usd: type: - number - "null" parent_execution_id: type: - string - "null" format: uuid description: Previous round of the conversation (conversational Task); null on the first. root_execution_id: type: - string - "null" format: uuid description: First round of the conversation; null on itself. required: - id - organization_id - workspace_id - activity_id - task_id - status - source - reference_date - started_at - finished_at - cost_usd - parent_execution_id - root_execution_id Memory: type: object properties: id: type: string format: uuid external_id: type: - string - "null" organization_id: type: string format: uuid workspace_id: type: - string - "null" format: uuid activity_id: type: - string - "null" format: uuid entity_type: type: - string - "null" entity_value: type: - string - "null" key: type: - string - "null" content: type: string summary: type: - string - "null" status: type: - string - "null" custom_metadata: type: object additionalProperties: {} system_metadata: type: object additionalProperties: {} created_at: type: string updated_at: type: string deleted_at: type: - string - "null" required: - id - external_id - organization_id - workspace_id - activity_id - entity_type - entity_value - key - content - summary - status - custom_metadata - system_metadata - created_at - updated_at - deleted_at Environment: type: object properties: id: type: string format: uuid organization_id: type: string format: uuid label: type: string color: type: string example: "#16a34a" branch: type: string description: Playbook branch used for the run. repo_managed: type: boolean description: "Declared in the organization repository's `kadu.yaml`: the sync recreates the environment and reapplies the declared color and branch. It cannot be deleted through the API." created_at: type: string updated_at: type: string deleted_at: type: - string - "null" required: - id - organization_id - label - color - branch - repo_managed - created_at - updated_at - deleted_at Secret: type: object properties: id: type: string format: uuid organization_id: type: string format: uuid environment_id: type: string format: uuid workspace_id: type: - string - "null" format: uuid description: null = applies to all workspaces of the organization. key: type: string notes: type: - string - "null" created_at: type: string updated_at: type: string deleted_at: type: - string - "null" required: - id - organization_id - environment_id - workspace_id - key - notes - created_at - updated_at - deleted_at description: "The value is write-only: no route returns it." Schedule: type: object properties: id: type: string format: uuid organization_id: type: string format: uuid task_id: type: string format: uuid environment_id: type: string format: uuid cron: type: string example: 0 9 * * 1-5 timezone: type: string example: America/Sao_Paulo paused: type: boolean paused_at: type: - string - "null" repo_managed: type: boolean description: "Declared in the skill frontmatter's `schedules`: the sync reapplies the declared cron, time zone and pause. It cannot be deleted through the API." created_at: type: string updated_at: type: string deleted_at: type: - string - "null" required: - id - organization_id - task_id - environment_id - cron - timezone - paused - paused_at - repo_managed - created_at - updated_at - deleted_at TaskEndpoint: type: object properties: task_id: type: string format: uuid endpoint: type: - object - "null" properties: enabled: type: boolean auth: type: string enum: - basic - bearer - header - params auth_basic_user: type: - string - "null" auth_header_key: type: - string - "null" auth_param_key: type: - string - "null" auth_basic_password_set: type: boolean auth_bearer_token_set: type: boolean auth_header_value_set: type: boolean auth_param_value_set: type: boolean required: - enabled - auth - auth_basic_user - auth_header_key - auth_param_key - auth_basic_password_set - auth_bearer_token_set - auth_header_value_set - auth_param_value_set description: null = the Task never had an endpoint configured. required: - task_id - endpoint File: type: object properties: id: type: string format: uuid organization_id: type: string format: uuid task_id: type: - string - "null" format: uuid execution_id: type: - string - "null" format: uuid kind: type: string enum: - input - output status: type: string enum: - pending - uploaded filename: type: string content_type: type: string size_bytes: type: number custom_metadata: type: object additionalProperties: {} created_at: type: string updated_at: type: string deleted_at: type: - string - "null" required: - id - organization_id - task_id - execution_id - kind - status - filename - content_type - size_bytes - custom_metadata - created_at - updated_at - deleted_at SlackInstallation: type: object properties: id: type: string format: uuid team_id: type: - string - "null" team_name: type: - string - "null" enterprise_id: type: - string - "null" is_enterprise_install: type: boolean settings: type: object properties: allowed_channel_types: type: array items: type: string enum: - im - private_channel - public_channel - mpim - shared_channel files_mode: type: string enum: - link - upload max_upload_bytes: type: integer log_detail: type: string enum: - milestones - verbose required: - allowed_channel_types - files_mode - max_upload_bytes - log_detail connected_users: type: integer created_at: type: string required: - id - team_id - team_name - enterprise_id - is_enterprise_install - settings - connected_users - created_at Todo: type: object properties: id: type: number execution_id: type: string format: uuid title: type: string description: type: - string - "null" status: type: string enum: - todo - resolved payload: {} resolved_at: type: - string - "null" created_at: type: string updated_at: type: string required: - id - execution_id - title - description - status - resolved_at - created_at - updated_at Webhook: type: object properties: id: type: string format: uuid external_id: type: - string - "null" label: type: string organization_id: type: string format: uuid workspace_id: type: - string - "null" format: uuid status: type: string enum: - active - inactive auth: type: string enum: - basic - bearer - header auth_basic_user: type: - string - "null" auth_header_key: type: - string - "null" auth_configured: type: boolean url: type: string subscribed_events: type: array items: type: string previous_signing_secret_expires_at: type: - string - "null" consecutive_failures: type: number emails: type: array items: type: object properties: address: type: string required: - address repo_managed: type: boolean description: "Declared in `kadu.yaml`: the sync reapplies URL, events, status, emails and metadata; credentials and the signing secret are still set through the API. It cannot be deleted through the API." custom_metadata: type: object additionalProperties: {} created_at: type: string updated_at: type: string deleted_at: type: - string - "null" required: - id - external_id - label - organization_id - workspace_id - status - auth - auth_basic_user - auth_header_key - auth_configured - url - subscribed_events - previous_signing_secret_expires_at - consecutive_failures - emails - repo_managed - custom_metadata - created_at - updated_at - deleted_at description: Secrets and credentials are never returned. WebhookDelivery: type: object properties: id: type: string format: uuid webhook_id: type: string format: uuid system_event_id: type: string format: uuid attempt: type: number status: type: string enum: - pending - success - failed request_headers: type: object additionalProperties: type: string description: Authentication headers appear as `[redacted]`. request_body: {} response_status: type: - number - "null" response_headers: type: - object - "null" additionalProperties: type: string response_body: type: - string - "null" error: type: - string - "null" duration_ms: type: - number - "null" delivered_at: type: - string - "null" next_retry_at: type: - string - "null" created_at: type: string updated_at: type: string required: - id - webhook_id - system_event_id - attempt - status - request_headers - response_status - response_headers - response_body - error - duration_ms - delivered_at - next_retry_at - created_at - updated_at OperationApproval: type: object properties: id: type: string format: uuid status: type: string enum: - pending - approved - executed - declined - failed - expired description: "`pending` (waiting for the decision, within the deadline), `approved` (confirmed, processing), `executed`, `declined` (cancelled), `failed` (confirmed, but the execution failed), `expired` (the link expired without a decision — includes a lapsed pending one)." resource: type: string description: API resource affected, e.g. `tasks`. example: tasks operation: type: string description: Operation on the resource, e.g. `run`. example: run action: type: string description: MCP tool that asked. example: kadu_tasks_run requester: type: object properties: client_id: type: - string - "null" description: OAuth client of the token that asked (verified). null = personal token. client_name: type: - string - "null" description: Name the MCP client declared about itself (not verified). required: - client_id - client_name created_at: type: string expires_at: type: string decided_at: type: - string - "null" executed_at: type: - string - "null" required: - id - status - resource - operation - action - requester - created_at - expires_at - decided_at - executed_at OperationApprovalDetail: allOf: - $ref: "#/components/schemas/OperationApproval" - type: object properties: organization_name: type: - string - "null" card: type: object additionalProperties: {} description: "What the approval screen shows: affected records (`sections`), labeled arguments (`args`) and unlabeled ones (`other`). After the decision, the snapshot of what was decided." args: type: object additionalProperties: {} description: Arguments of the call. result: description: "Response of the operation, or `{ error: { code, message } }`. Secrets masked." required: - organization_name - card - args Role: type: object properties: id: type: string format: uuid external_id: type: - string - "null" label: type: string organization_id: type: string format: uuid permissions: type: array items: type: string custom_metadata: type: object additionalProperties: {} created_at: type: string updated_at: type: string required: - id - external_id - label - organization_id - permissions - custom_metadata - created_at - updated_at User: type: object properties: id: type: string format: uuid external_id: type: - string - "null" name: type: - string - "null" email: type: - string - "null" role_id: type: string format: uuid last_sign_in_at: type: - string - "null" created_at: type: string required: - id - external_id - name - email - role_id - last_sign_in_at - created_at Membership: type: object properties: id: type: string format: uuid external_id: type: - string - "null" organization_id: type: string format: uuid user_id: type: string format: uuid role_id: type: string format: uuid custom_metadata: type: object additionalProperties: {} created_at: type: string updated_at: type: string required: - id - external_id - organization_id - user_id - role_id - custom_metadata - created_at - updated_at SystemEvent: type: object properties: id: type: string format: uuid slug: type: string example: execution.created organization_id: type: string format: uuid workspace_id: type: - string - "null" format: uuid activity_id: type: - string - "null" format: uuid task_id: type: - string - "null" format: uuid execution_id: type: - string - "null" format: uuid actor_user_id: type: - string - "null" format: uuid payload: {} created_at: type: string required: - id - slug - organization_id - workspace_id - activity_id - task_id - execution_id - actor_user_id - created_at parameters: {} paths: /v1/me: get: tags: - Identity summary: Identity behind the token description: "Returns the person, the organization and the token (type, scopes, access level, expiration) of the Bearer credential. Use it to test whether the configured token is valid: it is the only route exempt from the scope check, so any valid token gets a response. `user` is the person in `sub` when the token carries an email, and null for a machine token. It never returns the token itself." security: - bearerAuth: [] responses: "200": description: OK content: application/json: schema: type: object properties: data: type: object properties: user: type: - object - "null" properties: id: type: string name: type: - string - "null" email: type: string required: - id - name - email organization: type: object properties: id: type: string format: uuid name: type: string external_id: type: - string - "null" required: - id - name - external_id token: type: object properties: type: type: string enum: - oauth scopes: type: array items: type: string access_level: type: string enum: - read - write - all expires_at: type: - string - "null" required: - type - scopes - access_level - expires_at required: - user - organization - token required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization. content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: get-me /v1/organizations: get: tags: - Organizations summary: List organizations security: - bearerAuth: [] parameters: - schema: type: string required: false name: cursor in: query - schema: type: number minimum: 1 maximum: 100 required: false name: limit in: query - schema: type: string description: "Field in snake_case: created_at (default), updated_at or a filterable field." required: false description: "Field in snake_case: created_at (default), updated_at or a filterable field." name: sort_by in: query - schema: type: string enum: - asc - desc description: "Default: desc." required: false description: "Default: desc." name: sort_order in: query responses: "200": description: OK content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/Organization" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: get-organizations /v1/organizations/{id}: get: tags: - Organizations summary: Get organization details security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path responses: "200": description: OK content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Organization" required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: not found content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: get-organizations-id patch: tags: - Organizations summary: Update the token's organization description: "`monthly_cost_limit` and `bypass_subscription` are set by Kobana and rejected (403). Another organization: 403." security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path - schema: type: string minLength: 1 maxLength: 255 description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." required: false description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." name: X-Idempotency-Key in: header requestBody: content: application/json: schema: type: object properties: label: type: string minLength: 1 maxLength: 255 timezone: type: string example: America/Sao_Paulo custom_metadata: type: object additionalProperties: {} responses: "200": description: OK content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Organization" required: - data "400": description: VALIDATION_ERROR content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: FORBIDDEN content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: NOT_FOUND content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: IDEMPOTENCY_KEY_REUSED / IDEMPOTENCY_REQUEST_IN_PROGRESS (or the route's CONFLICT) content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: patch-organizations-id /v1/workspaces: get: tags: - Workspaces summary: List workspaces security: - bearerAuth: [] parameters: - schema: type: string required: false name: cursor in: query - schema: type: number minimum: 1 maximum: 100 required: false name: limit in: query - schema: type: string description: "Field in snake_case: created_at (default), updated_at or a filterable field." required: false description: "Field in snake_case: created_at (default), updated_at or a filterable field." name: sort_by in: query - schema: type: string enum: - asc - desc description: "Default: desc." required: false description: "Default: desc." name: sort_order in: query responses: "200": description: OK content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/Workspace" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: get-workspaces post: tags: - Workspaces summary: Create workspace security: - bearerAuth: [] parameters: - schema: type: string minLength: 1 maxLength: 255 description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." required: false description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." name: X-Idempotency-Key in: header requestBody: content: application/json: schema: type: object properties: label: type: string minLength: 1 external_id: type: string minLength: 1 maxLength: 255 description: Record id in the source system (free text). custom_metadata: type: object additionalProperties: {} required: - label responses: "201": description: created content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Workspace" required: - data "400": description: VALIDATION_ERROR content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: CONFLICT — duplicate record / IDEMPOTENCY_KEY_REUSED content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: post-workspaces /v1/workspaces/{id}: get: tags: - Workspaces summary: Get workspace details security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path responses: "200": description: OK content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Workspace" required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: not found content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: get-workspaces-id patch: tags: - Workspaces summary: Update workspace security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path - schema: type: string minLength: 1 maxLength: 255 description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." required: false description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." name: X-Idempotency-Key in: header requestBody: content: application/json: schema: type: object properties: label: type: string minLength: 1 custom_metadata: type: object additionalProperties: {} responses: "200": description: OK content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Workspace" required: - data "400": description: VALIDATION_ERROR content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: NOT_FOUND content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: IDEMPOTENCY_KEY_REUSED / IDEMPOTENCY_REQUEST_IN_PROGRESS (or the route's CONFLICT) content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: patch-workspaces-id delete: tags: - Workspaces summary: Delete workspaces (soft delete) description: "Requires the `delete` level (or `all`): `write` does not delete. Cascade: the workspace's activities, tasks, executions, webhooks, memories and secrets; cancels schedules and disables the tasks' endpoint." security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path responses: "200": description: OK content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Workspace" required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: NOT_FOUND content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: delete-workspaces-id /v1/activities: get: tags: - Activities summary: List activities security: - bearerAuth: [] parameters: - schema: type: string required: false name: cursor in: query - schema: type: number minimum: 1 maximum: 100 required: false name: limit in: query - schema: type: string description: "Field in snake_case: created_at (default), updated_at or a filterable field." required: false description: "Field in snake_case: created_at (default), updated_at or a filterable field." name: sort_by in: query - schema: type: string enum: - asc - desc description: "Default: desc." required: false description: "Default: desc." name: sort_order in: query responses: "200": description: OK content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/Activity" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: get-activities post: tags: - Activities summary: Create activity security: - bearerAuth: [] parameters: - schema: type: string minLength: 1 maxLength: 255 description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." required: false description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." name: X-Idempotency-Key in: header requestBody: content: application/json: schema: type: object properties: label: type: string minLength: 1 workspace_id: type: string format: uuid external_id: type: string minLength: 1 maxLength: 255 description: Record id in the source system (free text). custom_metadata: type: object additionalProperties: {} required: - label - workspace_id responses: "201": description: created content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Activity" required: - data "400": description: VALIDATION_ERROR content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: IDEMPOTENCY_KEY_REUSED / IDEMPOTENCY_REQUEST_IN_PROGRESS (or the route's CONFLICT) content: application/json: schema: $ref: "#/components/schemas/Error" "422": description: VALIDATION_ERROR — workspace outside the organization content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: post-activities /v1/activities/{id}: get: tags: - Activities summary: Get activity details security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path responses: "200": description: OK content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Activity" required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: not found content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: get-activities-id patch: tags: - Activities summary: Update activity security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path - schema: type: string minLength: 1 maxLength: 255 description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." required: false description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." name: X-Idempotency-Key in: header requestBody: content: application/json: schema: type: object properties: label: type: string minLength: 1 custom_metadata: type: object additionalProperties: {} responses: "200": description: OK content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Activity" required: - data "400": description: VALIDATION_ERROR content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: NOT_FOUND content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: IDEMPOTENCY_KEY_REUSED / IDEMPOTENCY_REQUEST_IN_PROGRESS (or the route's CONFLICT) content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: patch-activities-id delete: tags: - Activities summary: Delete activities (soft delete) description: "Requires the `delete` level (or `all`): `write` does not delete. Cascade: the activity's tasks, executions and memories; cancels schedules and disables the tasks' endpoint." security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path responses: "200": description: OK content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Activity" required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: NOT_FOUND content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: delete-activities-id /v1/tasks: get: tags: - Tasks summary: List tasks security: - bearerAuth: [] parameters: - schema: type: string required: false name: cursor in: query - schema: type: number minimum: 1 maximum: 100 required: false name: limit in: query - schema: type: string description: "Field in snake_case: created_at (default), updated_at or a filterable field." required: false description: "Field in snake_case: created_at (default), updated_at or a filterable field." name: sort_by in: query - schema: type: string enum: - asc - desc description: "Default: desc." required: false description: "Default: desc." name: sort_order in: query responses: "200": description: OK content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/Task" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: get-tasks post: tags: - Tasks summary: Create task description: The task is created in the default pricing tier; tier and AI model are set by Kobana (`model` in the body is rejected). security: - bearerAuth: [] parameters: - schema: type: string minLength: 1 maxLength: 255 description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." required: false description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." name: X-Idempotency-Key in: header requestBody: content: application/json: schema: type: object properties: label: type: string minLength: 1 workspace_id: type: string format: uuid activity_id: type: string format: uuid skill_slug: type: string description: "`:` from the organization's repository: the workspace's plugin (when it has one), a skill present in the synced catalog (when there is a catalog), never `kadu:*`." example: finance:task-baixar-pagamentos-via-boleto-pix parameters_schema: type: - object - "null" additionalProperties: {} parameters_sensitive: type: boolean external_id: type: string minLength: 1 maxLength: 255 description: Record id in the source system (free text). custom_metadata: type: object additionalProperties: {} required: - label - workspace_id - activity_id - skill_slug responses: "201": description: created content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Task" required: - data "400": description: VALIDATION_ERROR content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: IDEMPOTENCY_KEY_REUSED / IDEMPOTENCY_REQUEST_IN_PROGRESS (or the route's CONFLICT) content: application/json: schema: $ref: "#/components/schemas/Error" "422": description: VALIDATION_ERROR — workspace/activity outside the organization or `skill_slug` not allowed content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: post-tasks /v1/tasks/{id}: get: tags: - Tasks summary: Get task details security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path responses: "200": description: OK content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Task" required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: not found content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: get-tasks-id patch: tags: - Tasks summary: Update task security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path - schema: type: string minLength: 1 maxLength: 255 description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." required: false description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." name: X-Idempotency-Key in: header requestBody: content: application/json: schema: type: object properties: label: type: string minLength: 1 skill_slug: type: string description: "`:` from the organization's repository: the workspace's plugin (when it has one), a skill present in the synced catalog (when there is a catalog), never `kadu:*`." example: finance:task-baixar-pagamentos-via-boleto-pix parameters_schema: type: - object - "null" additionalProperties: {} parameters_sensitive: type: boolean custom_metadata: type: object additionalProperties: {} responses: "200": description: OK content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Task" required: - data "400": description: VALIDATION_ERROR content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: FORBIDDEN — `model` is set by the tier (Kobana) content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: NOT_FOUND content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: IDEMPOTENCY_KEY_REUSED / IDEMPOTENCY_REQUEST_IN_PROGRESS (or the route's CONFLICT) content: application/json: schema: $ref: "#/components/schemas/Error" "422": description: VALIDATION_ERROR — `skill_slug` not allowed content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: patch-tasks-id delete: tags: - Tasks summary: Delete tasks (soft delete) description: "Requires the `delete` level (or `all`): `write` does not delete. Cascade: the task's executions and files; cancels schedules and disables the endpoint." security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path responses: "200": description: OK content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Task" required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: NOT_FOUND content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: delete-tasks-id /v1/tasks/{id}/run: post: tags: - Tasks summary: Run task security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path - schema: type: string minLength: 1 maxLength: 255 description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." required: false description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." name: X-Idempotency-Key in: header requestBody: content: application/json: schema: type: object properties: reference_date: type: string pattern: ^\d{4}-\d{2}-\d{2}$ parameters: type: object additionalProperties: {} default: {} environment_id: type: string format: uuid locale: type: string pattern: ^[a-z]{2}(-[A-Z]{2})?$ additional_instructions: type: string maxLength: 8000 input_file_ids: type: array items: type: string format: uuid maxItems: 50 description: Files uploaded through `POST /files` (confirmed and not yet used). mode: type: string enum: - default - resolve_pendencies default: default description: "`resolve_pendencies` only resolves the pending items of the Task's previous executions (console: \"Resolve pending items\"); `parameters` is ignored." required: - reference_date - environment_id responses: "201": description: created content: application/json: schema: type: object properties: data: type: object properties: execution_id: type: string format: uuid status: type: string enum: - queued required: - execution_id - status required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: 'INSUFFICIENT_SCOPE — requires `write` (or `all`). ENTITLEMENT_REQUIRED — the organization has no contracted Kadu plan (nor a current courtesy). details: { reason: "no_plan" | "missing_product", required_product: string | null }. Checked before the monthly cost cap.' content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: IDEMPOTENCY_KEY_REUSED / IDEMPOTENCY_REQUEST_IN_PROGRESS (or the route's CONFLICT) content: application/json: schema: $ref: "#/components/schemas/Error" "422": description: COST_LIMIT_REACHED / INVALID_PARAMETERS / ENVIRONMENT_REQUIRED / MISSING_SECRETS (details.keys) / INVALID_INPUT_FILES content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: post-tasks-id-run /v1/executions: get: tags: - Executions summary: List executions security: - bearerAuth: [] parameters: - schema: type: string required: false name: cursor in: query - schema: type: number minimum: 1 maximum: 100 required: false name: limit in: query - schema: type: string description: "Field in snake_case: created_at (default), updated_at or a filterable field." required: false description: "Field in snake_case: created_at (default), updated_at or a filterable field." name: sort_by in: query - schema: type: string enum: - asc - desc description: "Default: desc." required: false description: "Default: desc." name: sort_order in: query responses: "200": description: OK content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/Execution" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: get-executions /v1/executions/{id}: get: tags: - Executions summary: Get execution details security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path responses: "200": description: OK content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Execution" required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: not found content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: get-executions-id /v1/executions/{id}/cancel: post: tags: - Executions security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path - schema: type: string minLength: 1 maxLength: 255 description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." required: false description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." name: X-Idempotency-Key in: header responses: "200": description: cancelled (or the current terminal status, if already finished) content: application/json: schema: type: object properties: data: type: object properties: id: type: string format: uuid status: type: string required: - id - status required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: NOT_FOUND content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: IDEMPOTENCY_KEY_REUSED / IDEMPOTENCY_REQUEST_IN_PROGRESS (or the route's CONFLICT) content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: post-executions-id-cancel summary: Cancel the execution /v1/executions/{id}/continue: post: tags: - Executions summary: Continue the conversation (next round) description: "Only for a conversational Task (`conversational`): creates a child execution of this one that resumes the agent session (context, output files and state) and handles the request in `message`. It uses this execution's parameters, reference date and environment, and this execution must be finished (`success` or `failed`). Continuing an older round opens a branch. The new execution carries `parentExecutionId` (this one) and `rootExecutionId` (the first round)." security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path - schema: type: string minLength: 1 maxLength: 255 description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." required: false description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." name: X-Idempotency-Key in: header requestBody: content: application/json: schema: type: object properties: message: type: string minLength: 1 maxLength: 8000 locale: type: string pattern: ^[a-z]{2}(-[A-Z]{2})?$ input_file_ids: type: array items: type: string format: uuid maxItems: 50 description: New files for this round (`POST /files`, not yet used). required: - message responses: "201": description: round created (in the Task queue) content: application/json: schema: type: object properties: data: type: object properties: execution_id: type: string format: uuid parent_execution_id: type: string format: uuid status: type: string enum: - queued required: - execution_id - parent_execution_id - status required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: NOT_FOUND content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: NOT_CONVERSATIONAL / EXECUTOR_NOT_SUPPORTED / EXECUTOR_CHANGED / NOT_FINISHED / SESSION_UNAVAILABLE content: application/json: schema: $ref: "#/components/schemas/Error" "422": description: ENVIRONMENT_REQUIRED / MISSING_SECRETS (details.keys) / INVALID_PARAMETERS / INVALID_INPUT_FILES / COST_LIMIT_REACHED content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: post-executions-id-continue /v1/memories: get: tags: - Memories summary: List memories security: - bearerAuth: [] parameters: - schema: type: string required: false name: cursor in: query - schema: type: number minimum: 1 maximum: 100 required: false name: limit in: query - schema: type: string description: "Field in snake_case: created_at (default), updated_at or a filterable field." required: false description: "Field in snake_case: created_at (default), updated_at or a filterable field." name: sort_by in: query - schema: type: string enum: - asc - desc description: "Default: desc." required: false description: "Default: desc." name: sort_order in: query responses: "200": description: OK content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/Memory" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: get-memories post: tags: - Memories summary: Create memory security: - bearerAuth: [] parameters: - schema: type: string minLength: 1 maxLength: 255 description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." required: false description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." name: X-Idempotency-Key in: header requestBody: content: application/json: schema: type: object properties: content: type: string minLength: 1 workspace_id: type: - string - "null" format: uuid activity_id: type: - string - "null" format: uuid entity_type: type: - string - "null" minLength: 1 entity_value: type: - string - "null" minLength: 1 key: type: - string - "null" minLength: 1 summary: type: - string - "null" status: type: - string - "null" external_id: type: - string - "null" minLength: 1 maxLength: 255 custom_metadata: type: object additionalProperties: {} required: - content responses: "201": description: created content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Memory" required: - data "400": description: VALIDATION_ERROR content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: CONFLICT (duplicate external_id in the organization) / IDEMPOTENCY_KEY_REUSED content: application/json: schema: $ref: "#/components/schemas/Error" "422": description: VALIDATION_ERROR — workspace/activity outside the organization content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: post-memories /v1/memories/{id}: get: tags: - Memories summary: Get memory details security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path responses: "200": description: OK content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Memory" required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: not found content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: get-memories-id patch: tags: - Memories summary: Update memory security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path - schema: type: string minLength: 1 maxLength: 255 description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." required: false description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." name: X-Idempotency-Key in: header requestBody: content: application/json: schema: type: object properties: content: type: string minLength: 1 workspace_id: type: - string - "null" format: uuid activity_id: type: - string - "null" format: uuid entity_type: type: - string - "null" minLength: 1 entity_value: type: - string - "null" minLength: 1 key: type: - string - "null" minLength: 1 summary: type: - string - "null" status: type: - string - "null" custom_metadata: type: object additionalProperties: {} responses: "200": description: OK content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Memory" required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: NOT_FOUND content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: IDEMPOTENCY_KEY_REUSED / IDEMPOTENCY_REQUEST_IN_PROGRESS (or the route's CONFLICT) content: application/json: schema: $ref: "#/components/schemas/Error" "422": description: VALIDATION_ERROR — workspace/activity outside the organization content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: patch-memories-id delete: tags: - Memories summary: Delete memory (soft delete) description: "Requires the `delete` level (or `all`): `write` does not delete." security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path responses: "200": description: OK content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Memory" required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: not found content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: delete-memories-id /v1/environments: get: tags: - Environments summary: List environments security: - bearerAuth: [] parameters: - schema: type: string required: false name: cursor in: query - schema: type: number minimum: 1 maximum: 100 required: false name: limit in: query - schema: type: string description: "Field in snake_case: created_at (default), updated_at or a filterable field." required: false description: "Field in snake_case: created_at (default), updated_at or a filterable field." name: sort_by in: query - schema: type: string enum: - asc - desc description: "Default: desc." required: false description: "Default: desc." name: sort_order in: query responses: "200": description: OK content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/Environment" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: get-environments post: tags: - Environments summary: Create environment security: - bearerAuth: [] parameters: - schema: type: string minLength: 1 maxLength: 255 description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." required: false description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." name: X-Idempotency-Key in: header requestBody: content: application/json: schema: type: object properties: label: type: string minLength: 1 color: type: string pattern: ^#[0-9a-fA-F]{6}$ branch: type: string minLength: 1 default: main required: - label - color responses: "201": description: created content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Environment" required: - data "400": description: VALIDATION_ERROR content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE (see above) or FEATURE_NOT_ENABLED — the operation is not enabled for the organization (the same permission that enables the screen in the console); `details: { permission }`." content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: CONFLICT — an active environment with this label already exists / IDEMPOTENCY_KEY_REUSED content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: post-environments /v1/environments/{id}: get: tags: - Environments summary: Get environment details security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path responses: "200": description: OK content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Environment" required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: not found content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: get-environments-id patch: tags: - Environments summary: Update environment security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path - schema: type: string minLength: 1 maxLength: 255 description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." required: false description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." name: X-Idempotency-Key in: header requestBody: content: application/json: schema: type: object properties: label: type: string minLength: 1 color: type: string pattern: ^#[0-9a-fA-F]{6}$ branch: type: string minLength: 1 responses: "200": description: OK content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Environment" required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE (see above) or FEATURE_NOT_ENABLED — the operation is not enabled for the organization (the same permission that enables the screen in the console); `details: { permission }`." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: NOT_FOUND content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: CONFLICT — label already in use / IDEMPOTENCY_KEY_REUSED content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: patch-environments-id delete: tags: - Environments summary: Delete environment (soft delete) description: Rejected while the environment has secrets or schedules. security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path responses: "200": description: OK content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Environment" required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE (see above) or FEATURE_NOT_ENABLED — the operation is not enabled for the organization (the same permission that enables the screen in the console); `details: { permission }`." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: NOT_FOUND content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: "ENVIRONMENT_IN_USE — `details: { secrets, schedules }` / REPO_MANAGED — declared in `kadu.yaml`: remove it from there" content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: delete-environments-id /v1/secrets: get: tags: - Secrets summary: List secrets security: - bearerAuth: [] parameters: - schema: type: string required: false name: cursor in: query - schema: type: number minimum: 1 maximum: 100 required: false name: limit in: query - schema: type: string description: "Field in snake_case: created_at (default), updated_at or a filterable field." required: false description: "Field in snake_case: created_at (default), updated_at or a filterable field." name: sort_by in: query - schema: type: string enum: - asc - desc description: "Default: desc." required: false description: "Default: desc." name: sort_order in: query responses: "200": description: OK content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/Secret" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: get-secrets post: tags: - Secrets summary: Create secret description: The value is stored encrypted and never returned. security: - bearerAuth: [] parameters: - schema: type: string minLength: 1 maxLength: 255 description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." required: false description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." name: X-Idempotency-Key in: header requestBody: content: application/json: schema: type: object properties: environment_id: type: string format: uuid workspace_id: type: - string - "null" format: uuid key: type: string minLength: 1 value: type: string notes: type: - string - "null" required: - environment_id - key - value responses: "201": description: created content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Secret" required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE (see above) or FEATURE_NOT_ENABLED — the operation is not enabled for the organization (the same permission that enables the screen in the console); `details: { permission }`." content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: IDEMPOTENCY_KEY_REUSED / IDEMPOTENCY_REQUEST_IN_PROGRESS (or the route's CONFLICT) content: application/json: schema: $ref: "#/components/schemas/Error" "422": description: VALIDATION_ERROR — environment or workspace outside the organization content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: post-secrets /v1/secrets/{id}: get: tags: - Secrets summary: Get secret details security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path responses: "200": description: OK content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Secret" required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: not found content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: get-secrets-id patch: tags: - Secrets summary: Update secret description: A missing or empty `value` keeps the stored value. security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path - schema: type: string minLength: 1 maxLength: 255 description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." required: false description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." name: X-Idempotency-Key in: header requestBody: content: application/json: schema: type: object properties: environment_id: type: string format: uuid workspace_id: type: - string - "null" format: uuid key: type: string minLength: 1 value: type: string notes: type: - string - "null" responses: "200": description: OK content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Secret" required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE (see above) or FEATURE_NOT_ENABLED — the operation is not enabled for the organization (the same permission that enables the screen in the console); `details: { permission }`." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: NOT_FOUND content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: IDEMPOTENCY_KEY_REUSED / IDEMPOTENCY_REQUEST_IN_PROGRESS (or the route's CONFLICT) content: application/json: schema: $ref: "#/components/schemas/Error" "422": description: VALIDATION_ERROR — environment or workspace outside the organization content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: patch-secrets-id delete: tags: - Secrets summary: Delete secret (soft delete) security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path responses: "200": description: OK content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Secret" required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE (see above) or FEATURE_NOT_ENABLED — the operation is not enabled for the organization (the same permission that enables the screen in the console); `details: { permission }`." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: NOT_FOUND content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: delete-secrets-id /v1/schedules: get: tags: - Schedules summary: List schedules security: - bearerAuth: [] parameters: - schema: type: string required: false name: cursor in: query - schema: type: number minimum: 1 maximum: 100 required: false name: limit in: query - schema: type: string description: "Field in snake_case: created_at (default), updated_at or a filterable field." required: false description: "Field in snake_case: created_at (default), updated_at or a filterable field." name: sort_by in: query - schema: type: string enum: - asc - desc description: "Default: desc." required: false description: "Default: desc." name: sort_order in: query responses: "200": description: OK content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/Schedule" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: get-schedules post: tags: - Schedules summary: Schedule a Task in an environment description: "One schedule per Task and environment. Schedules do not stack: the run is skipped if the Task already has an active or queued execution." security: - bearerAuth: [] parameters: - schema: type: string minLength: 1 maxLength: 255 description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." required: false description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." name: X-Idempotency-Key in: header requestBody: content: application/json: schema: type: object properties: task_id: type: string format: uuid environment_id: type: string format: uuid cron: type: string minLength: 1 timezone: type: string default: UTC paused: type: boolean default: false required: - task_id - environment_id - cron responses: "201": description: created content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Schedule" required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE (see above) or FEATURE_NOT_ENABLED — the operation is not enabled for the organization (the same permission that enables the screen in the console); `details: { permission }`." content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: CONFLICT — the Task already has a schedule in the environment (`details.schedule_id`) / IDEMPOTENCY_KEY_REUSED content: application/json: schema: $ref: "#/components/schemas/Error" "422": description: INVALID_CRON / VALIDATION_ERROR — Task or environment outside the organization content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: post-schedules /v1/schedules/{id}: get: tags: - Schedules summary: Get schedule details security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path responses: "200": description: OK content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Schedule" required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: not found content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: get-schedules-id patch: tags: - Schedules summary: Update, pause or resume a schedule description: "`paused: true` keeps the cron and makes the dispatcher skip the schedule." security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path - schema: type: string minLength: 1 maxLength: 255 description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." required: false description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." name: X-Idempotency-Key in: header requestBody: content: application/json: schema: type: object properties: cron: type: string minLength: 1 timezone: type: string paused: type: boolean responses: "200": description: OK content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Schedule" required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE (see above) or FEATURE_NOT_ENABLED — the operation is not enabled for the organization (the same permission that enables the screen in the console); `details: { permission }`." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: NOT_FOUND content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: IDEMPOTENCY_KEY_REUSED / IDEMPOTENCY_REQUEST_IN_PROGRESS (or the route's CONFLICT) content: application/json: schema: $ref: "#/components/schemas/Error" "422": description: INVALID_CRON content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: patch-schedules-id delete: tags: - Schedules summary: Cancel schedule (soft delete) description: A new POST for the same Task and environment re-enables the schedule. security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path responses: "200": description: OK content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Schedule" required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE (see above) or FEATURE_NOT_ENABLED — the operation is not enabled for the organization (the same permission that enables the screen in the console); `details: { permission }`." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: NOT_FOUND content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: "REPO_MANAGED — declared in the skill frontmatter's `schedules`: remove it from there" content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: delete-schedules-id /v1/tasks/{id}/endpoint: get: tags: - Tasks summary: Task HTTP run endpoint description: "Configuration of the public endpoint `POST /api/run-task/{task_id}`. Credentials are never returned: only the `*_set` flags." security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path responses: "200": description: OK content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/TaskEndpoint" required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE (see above) or FEATURE_NOT_ENABLED — the operation is not enabled for the organization (the same permission that enables the screen in the console); `details: { permission }`." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: NOT_FOUND content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: get-tasks-id-endpoint put: tags: - Tasks summary: Configure the Task's HTTP endpoint description: "Creates or updates. An omitted credential keeps the stored one as long as the auth type does not change. Avoid `auth: params`: the secret goes in the URL and ends up in proxy and CDN access logs; prefer `bearer` or `header`." security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path - schema: type: string minLength: 1 maxLength: 255 description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." required: false description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." name: X-Idempotency-Key in: header requestBody: content: application/json: schema: type: object properties: enabled: type: boolean auth: type: string enum: - basic - bearer - header - params auth_basic_user: type: string auth_basic_password: type: string auth_bearer_token: type: string auth_header_key: type: string auth_header_value: type: string auth_param_key: type: string auth_param_value: type: string required: - enabled - auth responses: "200": description: OK content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/TaskEndpoint" required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE (see above) or FEATURE_NOT_ENABLED — the operation is not enabled for the organization (the same permission that enables the screen in the console); `details: { permission }`." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: NOT_FOUND content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: IDEMPOTENCY_KEY_REUSED / IDEMPOTENCY_REQUEST_IN_PROGRESS (or the route's CONFLICT) content: application/json: schema: $ref: "#/components/schemas/Error" "422": description: INCOMPLETE_AUTH — credential missing for the chosen auth type content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: put-tasks-id-endpoint delete: tags: - Tasks summary: Disable the Task's HTTP endpoint description: "Keeps the configuration; a PUT with `enabled: true` re-enables it." security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path responses: "200": description: OK content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/TaskEndpoint" required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE (see above) or FEATURE_NOT_ENABLED — the operation is not enabled for the organization (the same permission that enables the screen in the console); `details: { permission }`." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: NOT_FOUND content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: delete-tasks-id-endpoint /v1/tasks/{id}/readiness: get: tags: - Tasks summary: Run pre-check description: "Whether the Task can run in the environment: valid environment and a value for every required secret (in the Task's workspace or global). Also returns the Task's queue. The run revalidates everything." security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path - schema: type: string format: uuid required: false name: environment_id in: query responses: "200": description: OK content: application/json: schema: type: object properties: data: type: object properties: ready: type: boolean environment: type: - object - "null" properties: id: type: string format: uuid label: type: string color: type: string required: - id - label - color required_secrets: type: array items: type: string missing_secrets: type: array items: type: string queue: type: object properties: active: type: - object - "null" properties: id: type: string format: uuid status: type: string required: - id - status queued: type: number required: - active - queued required: - ready - environment - required_secrets - missing_secrets - queue required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: NOT_FOUND content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: get-tasks-id-readiness /v1/files: get: tags: - Files summary: List files security: - bearerAuth: [] parameters: - schema: type: string required: false name: cursor in: query - schema: type: number minimum: 1 maximum: 100 required: false name: limit in: query - schema: type: string description: "Field in snake_case: created_at (default), updated_at or a filterable field." required: false description: "Field in snake_case: created_at (default), updated_at or a filterable field." name: sort_by in: query - schema: type: string enum: - asc - desc description: "Default: desc." required: false description: "Default: desc." name: sort_order in: query responses: "200": description: OK content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/File" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: get-files post: tags: - Files summary: Start an input file upload description: "Three-step flow: (1) this POST creates the `pending` file and returns `upload_url`; (2) `PUT` the bytes to `upload_url` with the same `Content-Type`; (3) `POST /files/{id}/confirm`. The id goes in `input_file_ids` of `POST /tasks/{id}/run` (the Task must accept input files). Maximum size: 100 MB." security: - bearerAuth: [] parameters: - schema: type: string minLength: 1 maxLength: 255 description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." required: false description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." name: X-Idempotency-Key in: header requestBody: content: application/json: schema: type: object properties: task_id: type: string format: uuid filename: type: string minLength: 1 maxLength: 255 content_type: type: string default: application/octet-stream size_bytes: type: integer minimum: 0 required: - task_id - filename - size_bytes responses: "201": description: created content: application/json: schema: type: object properties: data: type: object properties: id: type: string format: uuid filename: type: string content_type: type: string status: type: string enum: - pending upload_url: type: string expires_in: type: number description: Validity of `upload_url`, in seconds. required: - id - filename - content_type - status - upload_url - expires_in required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: IDEMPOTENCY_KEY_REUSED / IDEMPOTENCY_REQUEST_IN_PROGRESS (or the route's CONFLICT) content: application/json: schema: $ref: "#/components/schemas/Error" "422": description: TASK_DOES_NOT_ACCEPT_FILES / VALIDATION_ERROR — Task outside the organization content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: post-files /v1/files/{id}: get: tags: - Files summary: Get file details security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path responses: "200": description: OK content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/File" required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: not found content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: get-files-id /v1/files/{id}/confirm: post: tags: - Files summary: Confirm the upload (pending → uploaded) security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path - schema: type: string minLength: 1 maxLength: 255 description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." required: false description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." name: X-Idempotency-Key in: header responses: "200": description: OK content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/File" required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: NOT_FOUND content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: CONFLICT — not a pending input file / IDEMPOTENCY_KEY_REUSED content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: post-files-id-confirm /v1/files/{id}/download: get: tags: - Files summary: Temporary download URL security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path responses: "200": description: OK content: application/json: schema: type: object properties: data: type: object properties: id: type: string format: uuid url: type: string expires_in: type: number required: - id - url - expires_in required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: NOT_FOUND content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: FILE_NOT_UPLOADED content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: get-files-id-download /v1/executions/search: get: tags: - Executions summary: Text search across executions description: "Searches events, todos, logs, result and error. Up to 30 executions, most recent first, each with up to 3 snippets. Only sources the caller could read directly are included: logs require the organization's `executions_logs.view` permission, and on a person's token the role needs `agent.logs.list`, `agent.events.list` and `agent.todos.list` for logs, events and todos." security: - bearerAuth: [] parameters: - schema: type: string minLength: 2 required: true name: q in: query responses: "200": description: OK content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string format: uuid skill: type: string status: type: string started_at: type: string finished_at: type: - string - "null" workspace_label: type: - string - "null" activity_label: type: - string - "null" task_label: type: - string - "null" matches: type: array items: type: object properties: source: type: string enum: - event - result - logs - error - todo snippet: type: string required: - source - snippet required: - id - skill - status - started_at - finished_at - workspace_label - activity_label - task_label - matches required: - data "400": description: VALIDATION_ERROR — `q` shorter than 2 characters content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "429": description: "RATE_LIMITED — the search has its own limit: 30 per minute per token" content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: get-executions-search /v1/executions/{id}/logs: get: tags: - Executions summary: Execution logs description: In order of arrival, up to 1000 per call. To follow a running execution, pass the last `id` received in `after_id` and repeat. security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path - schema: type: - integer - "null" required: false name: after_id in: query responses: "200": description: OK content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: number execution_id: type: string format: uuid occurred_at: type: string level: type: string text: type: string required: - id - execution_id - occurred_at - level - text meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: NOT_FOUND content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: get-executions-id-logs /v1/executions/{id}/events: get: tags: - Executions summary: Execution events description: By `sequence`, up to 500 per call. To follow along, pass the last `sequence` received in `after_sequence` and repeat. security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path - schema: type: - integer - "null" required: false name: after_sequence in: query responses: "200": description: OK content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: number execution_id: type: string format: uuid sequence: type: number occurred_at: type: string type: type: string level: type: string step: type: - string - "null" message: type: string payload: {} required: - id - execution_id - sequence - occurred_at - type - level - step - message meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: NOT_FOUND content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: get-executions-id-events /v1/repository: get: tags: - Repository summary: Organization Kadu Playbook description: Connecting the repository means installing the GitHub App, done in the console (OAuth flow in the browser). security: - bearerAuth: [] responses: "200": description: OK content: application/json: schema: type: object properties: data: type: object properties: url: type: - string - "null" connection: type: - string - "null" enum: - github_app - deploy_key - null skills_count: type: number synced_at: type: - string - "null" sync_error: type: - string - "null" required: - url - connection - skills_count - synced_at - sync_error required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE (see above) or FEATURE_NOT_ENABLED — the operation is not enabled for the organization (the same permission that enables the screen in the console); `details: { permission }`." content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: get-repository /v1/repository/sync: post: tags: - Repository summary: Syncs the Kadu Playbook description: Queues the sync (the worker clones the repository and updates the Task catalog). Follow `synced_at` and `sync_error` in `GET /repository`. security: - bearerAuth: [] parameters: - schema: type: string minLength: 1 maxLength: 255 description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." required: false description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." name: X-Idempotency-Key in: header responses: "202": description: accepted content: application/json: schema: type: object properties: data: type: object properties: enqueued: type: boolean enum: - true required: - enqueued required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE (see above) or FEATURE_NOT_ENABLED — the operation is not enabled for the organization (the same permission that enables the screen in the console); `details: { permission }`." content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: IDEMPOTENCY_KEY_REUSED / IDEMPOTENCY_REQUEST_IN_PROGRESS (or the route's CONFLICT) content: application/json: schema: $ref: "#/components/schemas/Error" "422": description: NO_PLUGIN_REPO / NO_DEPLOY_KEY content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: QUEUE_UNAVAILABLE / AS_UNAVAILABLE content: application/json: schema: $ref: "#/components/schemas/Error" operationId: post-repository-sync /v1/usage: get: tags: - Usage summary: Usage and cost of executions and conversations description: "Aggregated per day (in the organization time zone) × group, adding executions and Slack bot conversation turns (source `slack_chat`, no workspace/activity/Task). Default: last 30 days; maximum period of 366 days. `group` is the id (tier, workspace, activity, task) or the source; null = no value." security: - bearerAuth: [] parameters: - schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ required: false name: from in: query - schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ required: false name: to in: query - schema: type: string enum: - tier - workspace - activity - task - source required: false name: group_by in: query - schema: type: string format: uuid required: false name: workspace_id in: query - schema: type: string format: uuid required: false name: activity_id in: query - schema: type: string format: uuid required: false name: task_id in: query - schema: type: string required: false name: source in: query responses: "200": description: OK content: application/json: schema: type: object properties: data: type: object properties: from: type: string to: type: string time_zone: type: string group_by: type: string totals: type: object properties: executions: type: number conversation_turns: type: number description: Slack bot conversation turns (source `slack_chat`). input_tokens: type: number output_tokens: type: number cache_read_tokens: type: number cache_write_tokens: type: number cost_brl: type: number description: Price in R$ (tokens × tier price). Only with Analytics › Cost enabled. required: - executions - conversation_turns - input_tokens - output_tokens - cache_read_tokens - cache_write_tokens buckets: type: array items: type: object properties: executions: type: number conversation_turns: type: number description: Slack bot conversation turns (source `slack_chat`). input_tokens: type: number output_tokens: type: number cache_read_tokens: type: number cache_write_tokens: type: number cost_brl: type: number description: Price in R$ (tokens × tier price). Only with Analytics › Cost enabled. date: type: string group: type: - string - "null" required: - executions - conversation_turns - input_tokens - output_tokens - cache_read_tokens - cache_write_tokens - date - group required: - from - to - time_zone - group_by - totals - buckets required: - data "400": description: VALIDATION_ERROR content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE (see above) or FEATURE_NOT_ENABLED — the operation is not enabled for the organization (the same permission that enables the screen in the console); `details: { permission }`." content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: get-usage /v1/organizations/{id}/slack_installations: get: tags: - Organizations summary: Slack bot installations of the organization description: "Slack workspaces linked to the token organization. Another organization: 403." security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path responses: "200": description: OK content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/SlackInstallation" required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: get-organizations-id-slack-installations /v1/organizations/{id}/slack_installations/{installationId}: patch: tags: - Organizations summary: Configures a Slack installation description: Where the bot answers (`allowed_channel_types`), output files as a link or attachment (`files_mode`, `max_upload_bytes` up to 100 MB) and detail in the thread (`log_detail`). security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path - schema: type: string format: uuid required: true name: installationId in: path - schema: type: string minLength: 1 maxLength: 255 description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." required: false description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." name: X-Idempotency-Key in: header requestBody: content: application/json: schema: type: object properties: allowed_channel_types: type: array items: type: string enum: - im - private_channel - public_channel - mpim - shared_channel minItems: 1 files_mode: type: string enum: - link - upload max_upload_bytes: type: integer exclusiveMinimum: 0 maximum: 104857600 log_detail: type: string enum: - milestones - verbose responses: "200": description: OK content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/SlackInstallation" required: - data "400": description: VALIDATION_ERROR content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: NOT_FOUND content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: IDEMPOTENCY_KEY_REUSED / IDEMPOTENCY_REQUEST_IN_PROGRESS (or the route's CONFLICT) content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: patch-organizations-id-slack-installations-installationid delete: tags: - Organizations summary: Removes a Slack installation description: Requires the `delete` level (or `all`). Revokes the bot token in Slack and undoes the account connections. security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path - schema: type: string format: uuid required: true name: installationId in: path responses: "200": description: OK content: application/json: schema: type: object properties: data: type: object properties: id: type: string format: uuid deleted: type: boolean required: - id - deleted required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: NOT_FOUND content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: delete-organizations-id-slack-installations-installationid /v1/executions/{id}/todos: get: tags: - Executions summary: Pending items (todos) of the execution security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path responses: "200": description: OK content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/Todo" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: NOT_FOUND content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: get-executions-id-todos /v1/todos/{id}: patch: tags: - Pending items summary: Resolve pending item description: "The only transition through the API: `status: resolved`." security: - bearerAuth: [] parameters: - schema: type: string pattern: ^\d+$ required: true name: id in: path - schema: type: string minLength: 1 maxLength: 255 description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." required: false description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." name: X-Idempotency-Key in: header requestBody: content: application/json: schema: type: object properties: status: type: string enum: - resolved responses: "200": description: OK content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Todo" required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: NOT_FOUND content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: IDEMPOTENCY_KEY_REUSED / IDEMPOTENCY_REQUEST_IN_PROGRESS (or the route's CONFLICT) content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: patch-todos-id /v1/webhooks: get: tags: - Webhooks summary: List webhooks security: - bearerAuth: [] parameters: - schema: type: string required: false name: cursor in: query - schema: type: number minimum: 1 maximum: 100 required: false name: limit in: query - schema: type: string description: "Field in snake_case: created_at (default), updated_at or a filterable field." required: false description: "Field in snake_case: created_at (default), updated_at or a filterable field." name: sort_by in: query - schema: type: string enum: - asc - desc description: "Default: desc." required: false description: "Default: desc." name: sort_order in: query responses: "200": description: OK content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/Webhook" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: get-webhooks post: tags: - Webhooks summary: Create webhook description: The URL is checked against the internal network. `signing_secret` is returned only in this response (an idempotency replay returns `null`). security: - bearerAuth: [] parameters: - schema: type: string minLength: 1 maxLength: 255 description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." required: false description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." name: X-Idempotency-Key in: header requestBody: content: application/json: schema: type: object properties: label: type: string minLength: 1 workspace_id: type: - string - "null" format: uuid url: type: string format: uri auth: type: string enum: - basic - bearer - header auth_basic_user: type: string auth_basic_password: type: string auth_bearer_token: type: string auth_header_key: type: string auth_header_value: type: string subscribed_events: type: array items: type: string default: [] emails: type: array items: type: object properties: address: type: string format: email required: - address default: [] required: - label - url - auth responses: "201": description: created content: application/json: schema: type: object properties: data: allOf: - $ref: "#/components/schemas/Webhook" - type: object properties: signing_secret: type: - string - "null" required: - signing_secret description: Secrets and credentials are never returned. required: - data "400": description: VALIDATION_ERROR content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: FEATURE_NOT_ENABLED — requires the organization's `webhooks.create` permission content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: IDEMPOTENCY_KEY_REUSED / IDEMPOTENCY_REQUEST_IN_PROGRESS (or the route's CONFLICT) content: application/json: schema: $ref: "#/components/schemas/Error" "422": description: VALIDATION_ERROR — workspace outside the organization content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: post-webhooks /v1/webhooks/{id}: get: tags: - Webhooks summary: Get webhook details security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path responses: "200": description: OK content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Webhook" required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: not found content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: get-webhooks-id patch: tags: - Webhooks summary: Update webhook security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path - schema: type: string minLength: 1 maxLength: 255 description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." required: false description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." name: X-Idempotency-Key in: header requestBody: content: application/json: schema: type: object properties: label: type: string minLength: 1 url: type: string format: uri subscribed_events: type: array items: type: string status: type: string enum: - active - inactive emails: type: array items: type: object properties: address: type: string format: email required: - address auth_basic_user: type: string auth_basic_password: type: string auth_bearer_token: type: string auth_header_key: type: string auth_header_value: type: string responses: "200": description: OK content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Webhook" required: - data "400": description: VALIDATION_ERROR content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: FEATURE_NOT_ENABLED — requires the organization's `webhooks.update` permission content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: NOT_FOUND content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: IDEMPOTENCY_KEY_REUSED / IDEMPOTENCY_REQUEST_IN_PROGRESS (or the route's CONFLICT) content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: patch-webhooks-id delete: tags: - Webhooks summary: Delete webhooks (soft delete) description: "Requires the `delete` level (or `all`): `write` does not delete. Requires the `webhooks.delete` permission. A webhook declared in `kadu.yaml` (`repo_managed`) responds 409 REPO_MANAGED: remove it from there." security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path responses: "200": description: OK content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Webhook" required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: NOT_FOUND content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: delete-webhooks-id /v1/webhooks/{id}/rotate-secret: post: tags: - Webhooks summary: Rotate the signing secret description: "Returns the new secret only in this response; the previous one keeps signing for 24h (an idempotency replay returns `signing_secret: null`)." security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path - schema: type: string minLength: 1 maxLength: 255 description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." required: false description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." name: X-Idempotency-Key in: header responses: "200": description: OK content: application/json: schema: type: object properties: data: type: object properties: id: type: string format: uuid signing_secret: type: - string - "null" previous_signing_secret_expires_at: type: string required: - id - signing_secret - previous_signing_secret_expires_at required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: NOT_FOUND content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: IDEMPOTENCY_KEY_REUSED / IDEMPOTENCY_REQUEST_IN_PROGRESS (or the route's CONFLICT) content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: post-webhooks-id-rotate-secret /v1/webhook_deliveries: get: tags: - Webhook deliveries summary: Webhook deliveries (50 most recent) security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: false name: webhook_id in: query - schema: type: string enum: - pending - success - failed required: false name: status in: query responses: "200": description: OK content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/WebhookDelivery" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta "400": description: BAD_REQUEST — invalid `status` or `webhook_id` content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: get-webhook-deliveries /v1/webhook_deliveries/{id}: get: tags: - Webhook deliveries summary: Get webhook delivery details security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path responses: "200": description: OK content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/WebhookDelivery" required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: not found content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: get-webhook-deliveries-id /v1/webhook_deliveries/{id}/replay: post: tags: - Webhook deliveries summary: Requeue the delivery security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path - schema: type: string minLength: 1 maxLength: 255 description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." required: false description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." name: X-Idempotency-Key in: header responses: "202": description: accepted content: application/json: schema: type: object properties: data: type: object properties: webhook_delivery_id: type: string format: uuid webhook_id: type: string format: uuid system_event_id: type: string format: uuid enqueued: type: boolean enum: - true required: - webhook_delivery_id - webhook_id - system_event_id - enqueued required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: NOT_FOUND content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: REPLAY_IN_FLIGHT — a resend of this event is already pending / IDEMPOTENCY_KEY_REUSED content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: post-webhook-deliveries-id-replay /v1/operation_approvals: get: tags: - Approvals summary: Approvals by link of the token's person description: "Operations an assistant requested through MCP that only run after the person confirms them by link in the console. Lists only the approvals of the token's person, in the token's organization, newest first. Read-only: Continue and Cancel happen in the console. Scope: `kadu/system_events`." security: - bearerAuth: [] parameters: - schema: type: string enum: - pending - approved - executed - declined - failed - expired required: false name: status in: query - schema: type: string example: tasks required: false name: resource in: query - schema: type: string description: ISO 8601 (date or date and time). required: false description: ISO 8601 (date or date and time). name: created_at[gte] in: query - schema: type: string description: ISO 8601 (date or date and time). required: false description: ISO 8601 (date or date and time). name: created_at[lte] in: query - schema: type: string required: false name: cursor in: query - schema: type: number minimum: 1 maximum: 100 required: false name: limit in: query responses: "200": description: OK content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/OperationApproval" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta "400": description: VALIDATION_ERROR — invalid filter or cursor content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: PERSON_REQUIRED — the token is not of a person of the organization / INSUFFICIENT_SCOPE content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: get-operation-approvals /v1/operation_approvals/{id}: get: tags: - Approvals summary: Get an approval by link security: - bearerAuth: [] parameters: - schema: type: string format: uuid required: true name: id in: path responses: "200": description: OK content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/OperationApprovalDetail" required: - data "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: PERSON_REQUIRED — the token is not of a person of the organization / INSUFFICIENT_SCOPE content: application/json: schema: $ref: "#/components/schemas/Error" "404": description: NOT_FOUND content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: get-operation-approvals-id /v1/roles: get: tags: - Roles summary: List roles security: - bearerAuth: [] parameters: - schema: type: string required: false name: cursor in: query - schema: type: number minimum: 1 maximum: 100 required: false name: limit in: query - schema: type: string description: "Field in snake_case: created_at (default), updated_at or a filterable field." required: false description: "Field in snake_case: created_at (default), updated_at or a filterable field." name: sort_by in: query - schema: type: string enum: - asc - desc description: "Default: desc." required: false description: "Default: desc." name: sort_order in: query responses: "200": description: OK content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/Role" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: get-roles post: tags: - Roles summary: Create role description: Permissions in the format `*`, `agent.*`, `agent..*` or `agent..`. On a person's token, none can go beyond the role of whoever creates it. security: - bearerAuth: [] parameters: - schema: type: string minLength: 1 maxLength: 255 description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." required: false description: "Opaque key (up to 255 characters), valid for 24h within the organization. The same key + the same request returns the original response with `X-Idempotent-Replay: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSED. A one-time secret (`signing_secret` on webhook creation and rotation) is not stored: on replay it comes back as `null`." name: X-Idempotency-Key in: header requestBody: content: application/json: schema: type: object properties: label: type: string minLength: 1 maxLength: 255 permissions: type: array items: type: string maxItems: 200 default: [] required: - label responses: "201": description: created content: application/json: schema: type: object properties: data: $ref: "#/components/schemas/Role" required: - data "400": description: VALIDATION_ERROR content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: PERMISSION_ESCALATION — `details.permissions` lists what exceeds your role content: application/json: schema: $ref: "#/components/schemas/Error" "409": description: IDEMPOTENCY_KEY_REUSED / IDEMPOTENCY_REQUEST_IN_PROGRESS (or the route's CONFLICT) content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: post-roles /v1/users: get: tags: - Users summary: Organization members (up to 100) security: - bearerAuth: [] responses: "200": description: OK content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/User" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: get-users /v1/memberships: get: tags: - Memberships summary: List memberships security: - bearerAuth: [] parameters: - schema: type: string required: false name: cursor in: query - schema: type: number minimum: 1 maximum: 100 required: false name: limit in: query - schema: type: string description: "Field in snake_case: created_at (default), updated_at or a filterable field." required: false description: "Field in snake_case: created_at (default), updated_at or a filterable field." name: sort_by in: query - schema: type: string enum: - asc - desc description: "Default: desc." required: false description: "Default: desc." name: sort_order in: query responses: "200": description: OK content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/Membership" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: get-memberships /v1/system_events: get: tags: - System events summary: System events (100 most recent) security: - bearerAuth: [] parameters: - schema: type: string required: false name: slug in: query - schema: type: string format: uuid required: false name: workspace_id in: query - schema: type: string format: uuid required: false name: task_id in: query - schema: type: string format: uuid required: false name: execution_id in: query responses: "200": description: OK content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/SystemEvent" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta "400": description: VALIDATION_ERROR — invalid filter content: application/json: schema: $ref: "#/components/schemas/Error" "401": description: INVALID_TOKEN / INVALID_AUDIENCE / INVALID_ISSUER / TOKEN_EXPIRED / TOKEN_REVOKED / MTLS_REQUIRED content: application/json: schema: $ref: "#/components/schemas/Error" "403": description: "INSUFFICIENT_SCOPE — the token lacks the access level (or the `kadu/…` resource) the operation requires; `details: { required, granted }`. USER_PERMISSION_DENIED — the role of the person who owns the token does not grant the operation; `details: { required }`. NOT_A_MEMBER — the person is not a member of the organization. FEATURE_NOT_ENABLED — the operation is not enabled for the organization; `details: { permission }`. UNKNOWN_ORGANIZATION — the token's `org` is not a Kadu organization." content: application/json: schema: $ref: "#/components/schemas/Error" "503": description: AS_UNAVAILABLE — token verification is unavailable (Authorization Server down or configuration missing). Try again (`Retry-After`). content: application/json: schema: $ref: "#/components/schemas/Error" operationId: get-system-events webhooks: {} tags: - name: Identity description: Who is behind the token. - name: Organizations description: "The token's organization: name, time zone, monthly cost cap and `custom_metadata`." - name: Workspaces description: Business domains of the organization. Each workspace is a plugin of the Kadu Playbook. - name: Activities description: Groupings of tasks within a workspace. - name: Tasks description: "The organization's executable skills: registration, run, pre-check and the HTTP run endpoint." - name: Executions description: Each run of a task, with logs, events, pending items and text search. - name: Pending items description: Pending items created by executions. - name: Files description: Input files (attached to the run) and output files (published by the execution). - name: Environments description: Execution environments (Production, Sandbox…). Each secret and schedule belongs to one. - name: Secrets description: Credentials delivered to executions. The value is stored encrypted and is never returned. - name: Schedules description: Recurring executions of a task in an environment, defined by a cron expression. - name: Memories description: "Organization memory: records per entity (`entity_type` + `entity_value`), scoped to the organization, a workspace or an activity." - name: Webhooks description: Signed HTTP notifications sent when events occur. - name: Webhook deliveries description: History and resending of webhook deliveries. - name: Approvals description: Operations an assistant requested through MCP that wait for the person's confirmation by link (read-only). - name: Repository description: The organization's Kadu Playbook and its sync. - name: Usage description: Tokens, cost and price of executions. - name: Users description: Organization members. - name: Memberships description: Links between people and the organization. - name: Roles description: Roles and the `agent.*` permissions they grant. - name: System events description: Organization events (the same ones that feed webhooks).