{ "openapi": "3.1.0", "info": { "title": "Kobana Autonomous Inbox API", "version": "1.2.0", "description": "Public REST API for the Kobana Autonomous Inbox.\n\nAuthentication: Bearer JWT (RS256, issued by the Kobana authorization server; `aud` includes `https://api.inbox[.].kobana.com.br`) plus mTLS terminated at CloudFront (passed through as the `cloudfront-viewer-mtls-client-cert-fingerprint` header). The JWT `org` claim (the Kobana account) resolves the caller organization; `sub` is the person and is carried for attribution only. Pick a workspace inside the organization with `X-Workspace-Id` when it has more than one.\n\nResource `{id}` endpoints (workspaces, inboxes, agents, webhooks) accept either the internal UUID or the resource `external_id`. POST endpoints that own an `external_id` accept it as an optional field and default it to the generated internal `id` when omitted. The `deleted_at` field is never returned in responses or in webhook payloads; soft-deleted records are filtered out instead.\n\nAll keys in responses and webhook payloads are `snake_case`. Webhook deliveries share the API serializer: the envelope carries `event` (`slug`, `id`), `delivered_at` and `workspace`; `data` nests resource snapshots (`organization`, `agent`, `inbox`, `email`, `agent_run`) plus the event-specific keys." }, "servers": [ { "url": "https://api.inbox.kobana.com.br", "description": "Production" }, { "url": "https://api.inbox.sandbox.kobana.com.br", "description": "Sandbox" }, { "url": "http://localhost:3028/api", "description": "Local dev" } ], "tags": [ { "name": "Workspaces" }, { "name": "Inboxes" }, { "name": "Emails" }, { "name": "Agents" }, { "name": "Agent runs" }, { "name": "Webhooks" }, { "name": "Webhook deliveries" }, { "name": "System events" }, { "name": "Secrets" }, { "name": "Workflow runs" }, { "name": "Usage" }, { "name": "LLM models" }, { "name": "Identity" } ], "paths": { "/v1/workspaces": { "get": { "operationId": "list-workspaces", "summary": "List workspaces", "description": "Scope: the organization of the token workspace — every live workspace of that organization is reachable; one outside it is a 404. A token whose workspace has no organization only sees itself. Keyset-paginated with typed filters.", "tags": [ "Workspaces" ], "security": [ { "bearerAuth": [ "inbox/workspaces" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned in `meta.next_cursor` of the previous page.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Comma-separated sort keys, `-` prefix for descending. Allowed: `created_at`, `updated_at`, `label`, `slug`. Default `-created_at`.", "schema": { "type": "string", "default": "-created_at" } }, { "name": "source", "in": "query", "required": false, "description": "Equality. Also `source[in]=a,b`.", "schema": { "type": "string" } }, { "name": "slug", "in": "query", "required": false, "description": "Equality. Also `slug[in]=a,b`.", "schema": { "type": "string" } }, { "name": "external_id", "in": "query", "required": false, "description": "Equality. Also `external_id[in]=a,b`.", "schema": { "type": "string" } }, { "name": "created_at", "in": "query", "required": false, "description": "Equality. Also `created_at[in]=a,b` and `created_at[gt|gte|lt|lte]`.", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at[gte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at[lte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_at", "in": "query", "required": false, "description": "Equality. Also `updated_at[in]=a,b` and `updated_at[gt|gte|lt|lte]`.", "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_at[gte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_at[lte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Page of results.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Workspace" } }, "meta": { "type": "object", "required": [ "next_cursor" ], "properties": { "next_cursor": { "type": "string", "nullable": true, "description": "Opaque keyset cursor for the next page; `null` on the last page." } } } } } } } }, "400": { "description": "Body failed Zod validation. `error.details` carries `formErrors`/`fieldErrors`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "create-workspace", "summary": "Create workspace", "tags": [ "Workspaces" ], "security": [ { "bearerAuth": [ "inbox/workspaces", "write" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Optional. 8-255 chars of [A-Za-z0-9_-:.]. A replay with the same key within 24h returns the original response; the same key with a different body returns 409 `conflict`.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceCreate" } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Workspace" } } } } } }, "400": { "description": "Body failed Zod validation. `error.details` carries `formErrors`/`fieldErrors`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Unique constraint violated (e.g. `external_id` or inbox `email` already in use).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Body validation that requires server-side context (e.g. inbox domain mismatch).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Requires a `src=system` token. The workspace is created inside the token organization. Scope: the organization of the token workspace — every live workspace of that organization is reachable; one outside it is a 404. A token whose workspace has no organization only sees itself." }, "put": { "operationId": "upsert-workspace", "summary": "Create or update workspace", "description": "Upsert. Takes the same body as POST plus the lookup keys `id` and `external_id`, matched in that order. A match is updated in place and returns 200 — fields absent from the body keep their stored value. No key, or no match, creates the workspace exactly as POST would and returns 201. Scope: the organization of the token workspace — every live workspace of that organization is reachable; one outside it is a 404. A token whose workspace has no organization only sees itself. Requires a `src=system` token; `external_id` cannot be changed on a matched workspace (409).", "tags": [ "Workspaces" ], "security": [ { "bearerAuth": [ "inbox/workspaces", "write" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Optional. 8-255 chars of [A-Za-z0-9_-:.]. A replay with the same key within 24h returns the original response; the same key with a different body returns 409 `conflict`.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceUpsert" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Workspace" } } } } } }, "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Workspace" } } } } } }, "400": { "description": "Body failed Zod validation. `error.details` carries `formErrors`/`fieldErrors`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Unique constraint violated (e.g. `external_id` or inbox `email` already in use).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Body validation that requires server-side context (e.g. inbox domain mismatch).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{id}": { "get": { "operationId": "get-workspace", "summary": "Get workspace", "description": "Accepts either the internal UUID or the resource `external_id`. Scope: the organization of the token workspace — every live workspace of that organization is reachable; one outside it is a 404. A token whose workspace has no organization only sees itself.", "tags": [ "Workspaces" ], "security": [ { "bearerAuth": [ "inbox/workspaces" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Accepts either the internal UUID or the resource `external_id`.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Workspace" } } } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "update-workspace", "summary": "Update workspace", "description": "Accepts either the internal UUID or the resource `external_id`. Scope: the organization of the token workspace — every live workspace of that organization is reachable; one outside it is a 404. A token whose workspace has no organization only sees itself. Changing `monthly_cost_limit` / `monthly_emails_limit` requires a `src=system` token.", "tags": [ "Workspaces" ], "security": [ { "bearerAuth": [ "inbox/workspaces", "write" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Optional. 8-255 chars of [A-Za-z0-9_-:.]. A replay with the same key within 24h returns the original response; the same key with a different body returns 409 `conflict`.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } }, { "name": "id", "in": "path", "required": true, "description": "Accepts either the internal UUID or the resource `external_id`.", "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceUpdate" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Workspace" } } } } } }, "400": { "description": "Body failed Zod validation. `error.details` carries `formErrors`/`fieldErrors`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Unique constraint violated (e.g. `external_id` or inbox `email` already in use).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Body validation that requires server-side context (e.g. inbox domain mismatch).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "delete-workspace", "summary": "Delete workspace", "description": "Accepts either the internal UUID or the resource `external_id`. Scope: the organization of the token workspace — every live workspace of that organization is reachable; one outside it is a 404. A token whose workspace has no organization only sees itself. Requires a `src=system` token.", "tags": [ "Workspaces" ], "security": [ { "bearerAuth": [ "inbox/workspaces", "write" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Optional. 8-255 chars of [A-Za-z0-9_-:.]. A replay with the same key within 24h returns the original response; the same key with a different body returns 409 `conflict`.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } }, { "name": "id", "in": "path", "required": true, "description": "Accepts either the internal UUID or the resource `external_id`.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "204": { "description": "No content." }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/inboxes": { "get": { "operationId": "list-inboxes", "summary": "List inboxes", "description": "Keyset-paginated. Filters are typed query params (`field=value`, `field[op]=value`); unknown filters, unsortable fields and malformed values are rejected with 400 `validation_failed`.", "tags": [ "Inboxes" ], "security": [ { "bearerAuth": [ "inbox/inboxes" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned in `meta.next_cursor` of the previous page.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Comma-separated sort keys, `-` prefix for descending. Allowed: `created_at`, `updated_at`, `label`, `slug`. Default `-created_at`.", "schema": { "type": "string", "default": "-created_at" } }, { "name": "status", "in": "query", "required": false, "description": "Equality. Also `status[in]=a,b`.", "schema": { "type": "string", "enum": [ "active", "inactive" ] } }, { "name": "agent_id", "in": "query", "required": false, "description": "Equality. Also `agent_id[in]=a,b`.", "schema": { "type": "string", "format": "uuid" } }, { "name": "slug", "in": "query", "required": false, "description": "Equality. Also `slug[in]=a,b`.", "schema": { "type": "string" } }, { "name": "email", "in": "query", "required": false, "description": "Equality. Also `email[in]=a,b`.", "schema": { "type": "string" } }, { "name": "external_id", "in": "query", "required": false, "description": "Equality. Also `external_id[in]=a,b`.", "schema": { "type": "string" } }, { "name": "created_at", "in": "query", "required": false, "description": "Equality. Also `created_at[in]=a,b` and `created_at[gt|gte|lt|lte]`.", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at[gte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at[lte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_at", "in": "query", "required": false, "description": "Equality. Also `updated_at[in]=a,b` and `updated_at[gt|gte|lt|lte]`.", "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_at[gte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_at[lte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Page of results.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Inbox" } }, "meta": { "type": "object", "required": [ "next_cursor" ], "properties": { "next_cursor": { "type": "string", "nullable": true, "description": "Opaque keyset cursor for the next page; `null` on the last page." } } } } } } } }, "400": { "description": "Body failed Zod validation. `error.details` carries `formErrors`/`fieldErrors`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "create-inbox", "summary": "Create inbox", "tags": [ "Inboxes" ], "security": [ { "bearerAuth": [ "inbox/inboxes", "write" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Optional. 8-255 chars of [A-Za-z0-9_-:.]. A replay with the same key within 24h returns the original response; the same key with a different body returns 409 `conflict`.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxCreate" } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Inbox" } } } } } }, "400": { "description": "Body failed Zod validation. `error.details` carries `formErrors`/`fieldErrors`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Unique constraint violated (e.g. `external_id` or inbox `email` already in use).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Body validation that requires server-side context (e.g. inbox domain mismatch).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "upsert-inbox", "summary": "Create or update inbox", "description": "Upsert. Takes the same body as POST plus the lookup keys `id` and `external_id`, matched in that order, then by `email`. A match is updated in place and returns 200 — fields absent from the body keep their stored value. No key, or no match, creates the inbox exactly as POST would and returns 201.", "tags": [ "Inboxes" ], "security": [ { "bearerAuth": [ "inbox/inboxes", "write" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Optional. 8-255 chars of [A-Za-z0-9_-:.]. A replay with the same key within 24h returns the original response; the same key with a different body returns 409 `conflict`.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxUpsert" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Inbox" } } } } } }, "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Inbox" } } } } } }, "400": { "description": "Body failed Zod validation. `error.details` carries `formErrors`/`fieldErrors`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Unique constraint violated (e.g. `external_id` or inbox `email` already in use).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Body validation that requires server-side context (e.g. inbox domain mismatch).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/inboxes/{id}": { "get": { "operationId": "get-inbox", "summary": "Get inbox", "description": "Accepts either the internal UUID or the resource `external_id`.", "tags": [ "Inboxes" ], "security": [ { "bearerAuth": [ "inbox/inboxes" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Accepts either the internal UUID or the resource `external_id`.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Inbox" } } } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "update-inbox", "summary": "Update inbox", "description": "Accepts either the internal UUID or the resource `external_id`.", "tags": [ "Inboxes" ], "security": [ { "bearerAuth": [ "inbox/inboxes", "write" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Optional. 8-255 chars of [A-Za-z0-9_-:.]. A replay with the same key within 24h returns the original response; the same key with a different body returns 409 `conflict`.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } }, { "name": "id", "in": "path", "required": true, "description": "Accepts either the internal UUID or the resource `external_id`.", "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxUpdate" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Inbox" } } } } } }, "400": { "description": "Body failed Zod validation. `error.details` carries `formErrors`/`fieldErrors`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Unique constraint violated (e.g. `external_id` or inbox `email` already in use).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Body validation that requires server-side context (e.g. inbox domain mismatch).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "delete-inbox", "summary": "Delete inbox", "description": "Accepts either the internal UUID or the resource `external_id`.", "tags": [ "Inboxes" ], "security": [ { "bearerAuth": [ "inbox/inboxes", "write" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Optional. 8-255 chars of [A-Za-z0-9_-:.]. A replay with the same key within 24h returns the original response; the same key with a different body returns 409 `conflict`.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } }, { "name": "id", "in": "path", "required": true, "description": "Accepts either the internal UUID or the resource `external_id`.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "204": { "description": "No content." }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/agents": { "get": { "operationId": "list-agents", "summary": "List agents", "description": "Keyset-paginated. Filters are typed query params (`field=value`, `field[op]=value`); unknown filters, unsortable fields and malformed values are rejected with 400 `validation_failed`.", "tags": [ "Agents" ], "security": [ { "bearerAuth": [ "inbox/agents" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned in `meta.next_cursor` of the previous page.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Comma-separated sort keys, `-` prefix for descending. Allowed: `created_at`, `updated_at`, `label`, `version`. Default `-created_at`.", "schema": { "type": "string", "default": "-created_at" } }, { "name": "llm_model", "in": "query", "required": false, "description": "Equality. Also `llm_model[in]=a,b`.", "schema": { "type": "string" } }, { "name": "external_id", "in": "query", "required": false, "description": "Equality. Also `external_id[in]=a,b`.", "schema": { "type": "string" } }, { "name": "created_at", "in": "query", "required": false, "description": "Equality. Also `created_at[in]=a,b` and `created_at[gt|gte|lt|lte]`.", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at[gte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at[lte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_at", "in": "query", "required": false, "description": "Equality. Also `updated_at[in]=a,b` and `updated_at[gt|gte|lt|lte]`.", "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_at[gte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_at[lte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Page of results.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } }, "meta": { "type": "object", "required": [ "next_cursor" ], "properties": { "next_cursor": { "type": "string", "nullable": true, "description": "Opaque keyset cursor for the next page; `null` on the last page." } } } } } } } }, "400": { "description": "Body failed Zod validation. `error.details` carries `formErrors`/`fieldErrors`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "create-agent", "summary": "Create agent", "tags": [ "Agents" ], "security": [ { "bearerAuth": [ "inbox/agents", "write" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Optional. 8-255 chars of [A-Za-z0-9_-:.]. A replay with the same key within 24h returns the original response; the same key with a different body returns 409 `conflict`.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCreate" } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Agent" } } } } } }, "400": { "description": "Body failed Zod validation. `error.details` carries `formErrors`/`fieldErrors`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Unique constraint violated (e.g. `external_id` or inbox `email` already in use).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Body validation that requires server-side context (e.g. inbox domain mismatch).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "upsert-agent", "summary": "Create or update agent", "description": "Upsert. Takes the same body as POST plus the lookup keys `id` and `external_id`, matched in that order. A match is updated in place and returns 200 — fields absent from the body keep their stored value. No key, or no match, creates the agent exactly as POST would and returns 201.", "tags": [ "Agents" ], "security": [ { "bearerAuth": [ "inbox/agents", "write" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Optional. 8-255 chars of [A-Za-z0-9_-:.]. A replay with the same key within 24h returns the original response; the same key with a different body returns 409 `conflict`.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentUpsert" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Agent" } } } } } }, "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Agent" } } } } } }, "400": { "description": "Body failed Zod validation. `error.details` carries `formErrors`/`fieldErrors`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Unique constraint violated (e.g. `external_id` or inbox `email` already in use).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Body validation that requires server-side context (e.g. inbox domain mismatch).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/agents/{id}": { "get": { "operationId": "get-agent", "summary": "Get agent", "description": "Accepts either the internal UUID or the resource `external_id`.", "tags": [ "Agents" ], "security": [ { "bearerAuth": [ "inbox/agents" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Accepts either the internal UUID or the resource `external_id`.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Agent" } } } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "update-agent", "summary": "Update agent", "description": "Accepts either the internal UUID or the resource `external_id`.", "tags": [ "Agents" ], "security": [ { "bearerAuth": [ "inbox/agents", "write" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Optional. 8-255 chars of [A-Za-z0-9_-:.]. A replay with the same key within 24h returns the original response; the same key with a different body returns 409 `conflict`.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } }, { "name": "id", "in": "path", "required": true, "description": "Accepts either the internal UUID or the resource `external_id`.", "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentUpdate" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Agent" } } } } } }, "400": { "description": "Body failed Zod validation. `error.details` carries `formErrors`/`fieldErrors`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Unique constraint violated (e.g. `external_id` or inbox `email` already in use).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Body validation that requires server-side context (e.g. inbox domain mismatch).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "delete-agent", "summary": "Delete agent", "description": "Accepts either the internal UUID or the resource `external_id`.", "tags": [ "Agents" ], "security": [ { "bearerAuth": [ "inbox/agents", "write" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Optional. 8-255 chars of [A-Za-z0-9_-:.]. A replay with the same key within 24h returns the original response; the same key with a different body returns 409 `conflict`.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } }, { "name": "id", "in": "path", "required": true, "description": "Accepts either the internal UUID or the resource `external_id`.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "204": { "description": "No content." }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks": { "get": { "operationId": "list-webhooks", "summary": "List webhooks", "description": "Keyset-paginated. Filters are typed query params (`field=value`, `field[op]=value`); unknown filters, unsortable fields and malformed values are rejected with 400 `validation_failed`.", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [ "inbox/webhooks" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned in `meta.next_cursor` of the previous page.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Comma-separated sort keys, `-` prefix for descending. Allowed: `created_at`, `updated_at`, `label`. Default `-created_at`.", "schema": { "type": "string", "default": "-created_at" } }, { "name": "status", "in": "query", "required": false, "description": "Equality. Also `status[in]=a,b`.", "schema": { "type": "string", "enum": [ "active", "inactive" ] } }, { "name": "inbox_id", "in": "query", "required": false, "description": "Equality. Also `inbox_id[in]=a,b`.", "schema": { "type": "string", "format": "uuid" } }, { "name": "external_id", "in": "query", "required": false, "description": "Equality. Also `external_id[in]=a,b`.", "schema": { "type": "string" } }, { "name": "created_at", "in": "query", "required": false, "description": "Equality. Also `created_at[in]=a,b` and `created_at[gt|gte|lt|lte]`.", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at[gte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at[lte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_at", "in": "query", "required": false, "description": "Equality. Also `updated_at[in]=a,b` and `updated_at[gt|gte|lt|lte]`.", "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_at[gte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_at[lte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Page of results.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "meta": { "type": "object", "required": [ "next_cursor" ], "properties": { "next_cursor": { "type": "string", "nullable": true, "description": "Opaque keyset cursor for the next page; `null` on the last page." } } } } } } } }, "400": { "description": "Body failed Zod validation. `error.details` carries `formErrors`/`fieldErrors`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "create-webhook", "summary": "Create webhook", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [ "inbox/webhooks", "write" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Optional. 8-255 chars of [A-Za-z0-9_-:.]. A replay with the same key within 24h returns the original response; the same key with a different body returns 409 `conflict`.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreate" } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Webhook" } } } } } }, "400": { "description": "Body failed Zod validation. `error.details` carries `formErrors`/`fieldErrors`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Unique constraint violated (e.g. `external_id` or inbox `email` already in use).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Body validation that requires server-side context (e.g. inbox domain mismatch).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "upsert-webhook", "summary": "Create or update webhook", "description": "Upsert. Takes the same body as POST plus the lookup keys `id` and `external_id`, matched in that order. A match is updated in place and returns 200 — fields absent from the body keep their stored value. No key, or no match, creates the webhook exactly as POST would and returns 201.", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [ "inbox/webhooks", "write" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Optional. 8-255 chars of [A-Za-z0-9_-:.]. A replay with the same key within 24h returns the original response; the same key with a different body returns 409 `conflict`.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookUpsert" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Webhook" } } } } } }, "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Webhook" } } } } } }, "400": { "description": "Body failed Zod validation. `error.details` carries `formErrors`/`fieldErrors`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Unique constraint violated (e.g. `external_id` or inbox `email` already in use).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Body validation that requires server-side context (e.g. inbox domain mismatch).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{id}": { "get": { "operationId": "get-webhook", "summary": "Get webhook", "description": "Accepts either the internal UUID or the resource `external_id`.", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [ "inbox/webhooks" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Accepts either the internal UUID or the resource `external_id`.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Webhook" } } } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "update-webhook", "summary": "Update webhook", "description": "Accepts either the internal UUID or the resource `external_id`.", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [ "inbox/webhooks", "write" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Optional. 8-255 chars of [A-Za-z0-9_-:.]. A replay with the same key within 24h returns the original response; the same key with a different body returns 409 `conflict`.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } }, { "name": "id", "in": "path", "required": true, "description": "Accepts either the internal UUID or the resource `external_id`.", "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookUpdate" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Webhook" } } } } } }, "400": { "description": "Body failed Zod validation. `error.details` carries `formErrors`/`fieldErrors`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Unique constraint violated (e.g. `external_id` or inbox `email` already in use).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Body validation that requires server-side context (e.g. inbox domain mismatch).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "delete-webhook", "summary": "Delete webhook", "description": "Accepts either the internal UUID or the resource `external_id`.", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [ "inbox/webhooks", "write" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Optional. 8-255 chars of [A-Za-z0-9_-:.]. A replay with the same key within 24h returns the original response; the same key with a different body returns 409 `conflict`.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } }, { "name": "id", "in": "path", "required": true, "description": "Accepts either the internal UUID or the resource `external_id`.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "204": { "description": "No content." }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/secrets": { "get": { "operationId": "list-secrets", "summary": "List secrets", "description": "Keyset-paginated. Filters are typed query params (`field=value`, `field[op]=value`); unknown filters, unsortable fields and malformed values are rejected with 400 `validation_failed`. The value is write-only: it is stored encrypted and is never returned by any endpoint. To rotate it, PATCH the row (or PUT by `key`) with a new `value`.", "tags": [ "Secrets" ], "security": [ { "bearerAuth": [ "inbox/secrets" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned in `meta.next_cursor` of the previous page.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Comma-separated sort keys, `-` prefix for descending. Allowed: `created_at`, `updated_at`, `key`. Default `-created_at`.", "schema": { "type": "string", "default": "-created_at" } }, { "name": "key", "in": "query", "required": false, "description": "Equality. Also `key[in]=a,b`.", "schema": { "type": "string" } }, { "name": "created_at", "in": "query", "required": false, "description": "Equality. Also `created_at[in]=a,b` and `created_at[gt|gte|lt|lte]`.", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at[gte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at[lte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_at", "in": "query", "required": false, "description": "Equality. Also `updated_at[in]=a,b` and `updated_at[gt|gte|lt|lte]`.", "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_at[gte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_at[lte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Page of results.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Secret" } }, "meta": { "type": "object", "required": [ "next_cursor" ], "properties": { "next_cursor": { "type": "string", "nullable": true, "description": "Opaque keyset cursor for the next page; `null` on the last page." } } } } } } } }, "400": { "description": "Body failed Zod validation. `error.details` carries `formErrors`/`fieldErrors`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "create-secret", "summary": "Create secret", "tags": [ "Secrets" ], "security": [ { "bearerAuth": [ "inbox/secrets", "write" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Optional. 8-255 chars of [A-Za-z0-9_-:.]. A replay with the same key within 24h returns the original response; the same key with a different body returns 409 `conflict`.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretCreate" } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Secret" } } } } } }, "400": { "description": "Body failed Zod validation. `error.details` carries `formErrors`/`fieldErrors`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Unique constraint violated (e.g. `external_id` or inbox `email` already in use).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Body validation that requires server-side context (e.g. inbox domain mismatch).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Store a secret an agent workflow can reference as `${{secrets.KEY}}`. A duplicate `key` in the workspace is refused with 409 `conflict`. The value is write-only: it is stored encrypted and is never returned by any endpoint. To rotate it, PATCH the row (or PUT by `key`) with a new `value`." }, "put": { "operationId": "upsert-secret", "summary": "Create or update secret", "description": "Upsert matched by `key` within the caller workspace — the rotation path, no id lookup needed. Creates with 201 when the key is new, replaces the value with 200 when it exists. The value is write-only: it is stored encrypted and is never returned by any endpoint. To rotate it, PATCH the row (or PUT by `key`) with a new `value`.", "tags": [ "Secrets" ], "security": [ { "bearerAuth": [ "inbox/secrets", "write" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Optional. 8-255 chars of [A-Za-z0-9_-:.]. A replay with the same key within 24h returns the original response; the same key with a different body returns 409 `conflict`.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretUpsert" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Secret" } } } } } }, "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Secret" } } } } } }, "400": { "description": "Body failed Zod validation. `error.details` carries `formErrors`/`fieldErrors`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Unique constraint violated (e.g. `external_id` or inbox `email` already in use).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Body validation that requires server-side context (e.g. inbox domain mismatch).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/secrets/{id}": { "get": { "operationId": "get-secret", "summary": "Get secret", "description": "Accepts either the internal UUID or the resource `external_id`.", "tags": [ "Secrets" ], "security": [ { "bearerAuth": [ "inbox/secrets" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Accepts either the internal UUID or the resource `external_id`.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Secret" } } } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "update-secret", "summary": "Update secret", "description": "Replace the value or the notes. `key` is immutable: workflows reference it by name, so renaming would break them silently — delete and re-create instead.", "tags": [ "Secrets" ], "security": [ { "bearerAuth": [ "inbox/secrets", "write" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Optional. 8-255 chars of [A-Za-z0-9_-:.]. A replay with the same key within 24h returns the original response; the same key with a different body returns 409 `conflict`.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } }, { "name": "id", "in": "path", "required": true, "description": "Accepts either the internal UUID or the resource `external_id`.", "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretUpdate" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Secret" } } } } } }, "400": { "description": "Body failed Zod validation. `error.details` carries `formErrors`/`fieldErrors`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Unique constraint violated (e.g. `external_id` or inbox `email` already in use).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Body validation that requires server-side context (e.g. inbox domain mismatch).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "delete-secret", "summary": "Delete secret", "description": "Soft-delete. Workflow steps referencing the key start failing with `secret not defined` from the next run on.", "tags": [ "Secrets" ], "security": [ { "bearerAuth": [ "inbox/secrets", "write" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Optional. 8-255 chars of [A-Za-z0-9_-:.]. A replay with the same key within 24h returns the original response; the same key with a different body returns 409 `conflict`.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } }, { "name": "id", "in": "path", "required": true, "description": "Accepts either the internal UUID or the resource `external_id`.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "204": { "description": "No content." }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workflow-runs": { "get": { "operationId": "list-workflow-runs", "summary": "List workflow runs", "description": "Keyset-paginated. Filters are typed query params (`field=value`, `field[op]=value`); unknown filters, unsortable fields and malformed values are rejected with 400 `validation_failed`. Steps are not embedded in the listing — `GET /v1/workflow-runs/{id}` returns them.", "tags": [ "Workflow runs" ], "security": [ { "bearerAuth": [ "inbox/workflow_runs" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned in `meta.next_cursor` of the previous page.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Comma-separated sort keys, `-` prefix for descending. Allowed: `created_at`, `updated_at`, `status`. Default `-created_at`.", "schema": { "type": "string", "default": "-created_at" } }, { "name": "status", "in": "query", "required": false, "description": "Equality. Also `status[in]=a,b`.", "schema": { "type": "string", "enum": [ "pending", "running", "success", "failed" ] } }, { "name": "email_id", "in": "query", "required": false, "description": "Equality. Also `email_id[in]=a,b`.", "schema": { "type": "string", "format": "uuid" } }, { "name": "inbox_id", "in": "query", "required": false, "description": "Equality. Also `inbox_id[in]=a,b`.", "schema": { "type": "string", "format": "uuid" } }, { "name": "agent_id", "in": "query", "required": false, "description": "Equality. Also `agent_id[in]=a,b`.", "schema": { "type": "string", "format": "uuid" } }, { "name": "agent_run_id", "in": "query", "required": false, "description": "Equality. Also `agent_run_id[in]=a,b`.", "schema": { "type": "string", "format": "uuid" } }, { "name": "created_at", "in": "query", "required": false, "description": "Equality. Also `created_at[in]=a,b` and `created_at[gt|gte|lt|lte]`.", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at[gte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at[lte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "finished_at", "in": "query", "required": false, "description": "Equality. Also `finished_at[in]=a,b` and `finished_at[gt|gte|lt|lte]`.", "schema": { "type": "string", "format": "date-time" } }, { "name": "finished_at[gte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "finished_at[lte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Page of results.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowRun" } }, "meta": { "type": "object", "required": [ "next_cursor" ], "properties": { "next_cursor": { "type": "string", "nullable": true, "description": "Opaque keyset cursor for the next page; `null` on the last page." } } } } } } } }, "400": { "description": "Body failed Zod validation. `error.details` carries `formErrors`/`fieldErrors`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workflow-runs/{id}": { "get": { "operationId": "get-workflow-run", "summary": "Get workflow run", "description": "The run with every step in execution order. Requests and responses are stored with secret values replaced by `[REDACTED]`; bodies are truncated to 4000 characters.", "tags": [ "Workflow runs" ], "security": [ { "bearerAuth": [ "inbox/workflow_runs" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Accepts either the internal UUID or the resource `external_id`.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WorkflowRun" } } } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/emails": { "get": { "operationId": "list-emails", "summary": "List emails", "description": "Keyset-paginated. Filters are typed query params (`field=value`, `field[op]=value`); unknown filters, unsortable fields and malformed values are rejected with 400 `validation_failed`.", "tags": [ "Emails" ], "security": [ { "bearerAuth": [ "inbox/emails" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned in `meta.next_cursor` of the previous page.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Comma-separated sort keys, `-` prefix for descending. Allowed: `created_at`, `updated_at`, `from`, `status`. Default `-created_at`.", "schema": { "type": "string", "default": "-created_at" } }, { "name": "status", "in": "query", "required": false, "description": "Equality. Also `status[in]=a,b`.", "schema": { "type": "string", "enum": [ "received", "approved", "rejected", "processing", "processed", "failed" ] } }, { "name": "inbox_id", "in": "query", "required": false, "description": "Equality. Also `inbox_id[in]=a,b`.", "schema": { "type": "string", "format": "uuid" } }, { "name": "agent_id", "in": "query", "required": false, "description": "Equality. Also `agent_id[in]=a,b`.", "schema": { "type": "string", "format": "uuid" } }, { "name": "message_id", "in": "query", "required": false, "description": "Equality. Also `message_id[in]=a,b`.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Equality. Also `from[in]=a,b`.", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "Rows whose `to` contains the value.", "schema": { "type": "string" } }, { "name": "created_at", "in": "query", "required": false, "description": "Equality. Also `created_at[in]=a,b` and `created_at[gt|gte|lt|lte]`.", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at[gte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at[lte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_at", "in": "query", "required": false, "description": "Equality. Also `updated_at[in]=a,b` and `updated_at[gt|gte|lt|lte]`.", "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_at[gte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_at[lte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "received_at", "in": "query", "required": false, "description": "Equality. Also `received_at[in]=a,b` and `received_at[gt|gte|lt|lte]`.", "schema": { "type": "string", "format": "date-time" } }, { "name": "received_at[gte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "received_at[lte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "processed_at", "in": "query", "required": false, "description": "Equality. Also `processed_at[in]=a,b` and `processed_at[gt|gte|lt|lte]`.", "schema": { "type": "string", "format": "date-time" } }, { "name": "processed_at[gte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "processed_at[lte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Page of results.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Email" } }, "meta": { "type": "object", "required": [ "next_cursor" ], "properties": { "next_cursor": { "type": "string", "nullable": true, "description": "Opaque keyset cursor for the next page; `null` on the last page." } } } } } } } }, "400": { "description": "Body failed Zod validation. `error.details` carries `formErrors`/`fieldErrors`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "create-email", "summary": "Submit a raw .eml", "description": "Stores an RFC 5322 message exactly as SES inbound would: raw object in the raw bucket, `Email` in `received`, and a `process-email` job — filters, agent and webhooks run as for real mail. Send the message either as `multipart/form-data` (field `file`, optional `inbox_id`) or as the request body with `Content-Type: message/rfc822` (optional `?inbox_id=`). Without `inbox_id` the inbox is resolved from the `To:` header among the caller workspace inboxes. A `Message-ID` already stored is rejected with 409 (`error.details.email_id` points at the existing email).", "tags": [ "Emails" ], "security": [ { "bearerAuth": [ "inbox/emails", "write" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "inbox_id", "in": "query", "required": false, "description": "Target inbox. Overridden by the multipart `inbox_id` field when both are sent.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "message/rfc822": { "schema": { "type": "string", "format": "binary" } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "The `.eml` file (max 20 MB)." }, "inbox_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "201": { "description": "Stored and queued for processing.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "queued" ], "properties": { "data": { "$ref": "#/components/schemas/Email" }, "queued": { "type": "boolean", "description": "False when the row was stored but the processing job could not be enqueued; reprocess later." } } } } } }, "400": { "description": "Empty body or missing multipart `file` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`inbox_id` does not exist in the caller workspace (`inbox_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`duplicate_message_id`: the `Message-ID` is already stored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "`payload_too_large`: message above 20 MB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "`unsupported_media_type`: body is neither multipart nor `message/rfc822`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`no_inbox_matches_to_header` (no workspace inbox matches the `To:` recipients) or `missing_recipient` (no usable `To:` header; pass `inbox_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/emails/{id}": { "get": { "operationId": "get-email", "summary": "Get email", "tags": [ "Emails" ], "security": [ { "bearerAuth": [ "inbox/emails" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Accepts either the internal UUID or the resource `external_id`.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Email" } } } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "delete-email", "summary": "Delete email", "description": "Soft-deletes the email (sets `deleted_at`). It stops appearing in lists and detail; the raw object is purged by the retention job.", "tags": [ "Emails" ], "security": [ { "bearerAuth": [ "inbox/emails", "write" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Accepts either the internal UUID or the resource `external_id`.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "204": { "description": "No content." }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/emails/{id}/eml": { "get": { "operationId": "download-original-eml", "summary": "Download original .eml", "tags": [ "Emails" ], "security": [ { "bearerAuth": [ "inbox/emails" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Accepts either the internal UUID or the resource `external_id`.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Raw RFC 5322 message stream.", "content": { "message/rfc822": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/emails/{id}/reprocess": { "post": { "operationId": "reprocess-email", "summary": "Reprocess email", "description": "Re-enqueues processing for the email regardless of current status.", "tags": [ "Emails" ], "security": [ { "bearerAuth": [ "inbox/emails" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Optional. 8-255 chars of [A-Za-z0-9_-:.]. A replay with the same key within 24h returns the original response; the same key with a different body returns 409 `conflict`.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } }, { "name": "id", "in": "path", "required": true, "description": "Accepts either the internal UUID or the resource `external_id`.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "202": { "description": "Accepted and queued.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "email_id", "queued" ], "properties": { "email_id": { "type": "string", "format": "uuid" }, "queued": { "type": "boolean", "enum": [ true ] } } } } } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/usage/summary": { "get": { "operationId": "get-usage-summary", "summary": "Usage summary", "description": "Emails processed, tokens and cost per UTC day over the range (successful agent runs only), plus the running monthly counters against the workspace limits. Cost is USD as billed by the AI Gateway.", "tags": [ "Usage" ], "security": [ { "bearerAuth": [ "inbox/usage" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "First UTC day, `YYYY-MM-DD`. Defaults to 29 days before `to`.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Last UTC day (inclusive), `YYYY-MM-DD`. Defaults to today.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/UsageSummary" } } } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/usage/cost": { "get": { "operationId": "get-usage-cost", "summary": "Cost by model", "description": "Cost and tokens per LLM model over the range: totals per model and a per-day series.", "tags": [ "Usage" ], "security": [ { "bearerAuth": [ "inbox/usage" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "First UTC day, `YYYY-MM-DD`. Defaults to 29 days before `to`.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Last UTC day (inclusive), `YYYY-MM-DD`. Defaults to today.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/UsageCost" } } } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/me": { "get": { "operationId": "get-me", "summary": "Identity behind the token", "description": "Who the Bearer token acts as: the person (`null` for a machine token), the organization and the token's own reach. Use it to test whether a configured token is valid. Requires no resource scope: any token that verifies is answered. The token itself is never returned.", "tags": [ "Identity" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Identity.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Me" } } } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated, but the token's organization or membership is unknown here.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/models": { "get": { "operationId": "list-models", "summary": "List available LLM models", "description": "Models accepted in `Agent.llm_model`, with per-token prices: the AI Gateway catalog narrowed to models that have a price, so every listed model is costed and counted against the workspace limit.", "tags": [ "LLM models" ], "security": [ { "bearerAuth": [ "inbox/agents" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Catalog.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } } } } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "`gateway_error`: the AI Gateway catalog could not be fetched.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/agents/{id}/versions": { "get": { "operationId": "list-agent-versions", "summary": "List agent prompt versions", "description": "Keyset-paginated. Filters are typed query params (`field=value`, `field[op]=value`); unknown filters, unsortable fields and malformed values are rejected with 400 `validation_failed`.", "tags": [ "Agents" ], "security": [ { "bearerAuth": [ "inbox/agents" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned in `meta.next_cursor` of the previous page.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Comma-separated sort keys, `-` prefix for descending. Allowed: `created_at`, `version`. Default `-version`.", "schema": { "type": "string", "default": "-version" } }, { "name": "id", "in": "path", "required": true, "description": "Accepts either the internal UUID or the resource `external_id`.", "schema": { "type": "string", "minLength": 1 } }, { "name": "version", "in": "query", "required": false, "description": "Equality. Also `version[in]=a,b` and `version[gt|gte|lt|lte]`.", "schema": { "type": "integer" } }, { "name": "version[gte]", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "version[lte]", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "created_at", "in": "query", "required": false, "description": "Equality. Also `created_at[in]=a,b` and `created_at[gt|gte|lt|lte]`.", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at[gte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at[lte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Page of results.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentVersion" } }, "meta": { "type": "object", "required": [ "next_cursor" ], "properties": { "next_cursor": { "type": "string", "nullable": true, "description": "Opaque keyset cursor for the next page; `null` on the last page." } } } } } } } }, "400": { "description": "Body failed Zod validation. `error.details` carries `formErrors`/`fieldErrors`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/agent-runs": { "get": { "operationId": "list-agent-runs", "summary": "List agent runs", "description": "Keyset-paginated. Filters are typed query params (`field=value`, `field[op]=value`); unknown filters, unsortable fields and malformed values are rejected with 400 `validation_failed`.", "tags": [ "Agent runs" ], "security": [ { "bearerAuth": [ "inbox/agent_runs" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned in `meta.next_cursor` of the previous page.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Comma-separated sort keys, `-` prefix for descending. Allowed: `created_at`, `updated_at`, `total_cost`, `status`. Default `-created_at`.", "schema": { "type": "string", "default": "-created_at" } }, { "name": "status", "in": "query", "required": false, "description": "Equality. Also `status[in]=a,b`.", "schema": { "type": "string", "enum": [ "running", "success", "failed" ] } }, { "name": "agent_id", "in": "query", "required": false, "description": "Equality. Also `agent_id[in]=a,b`.", "schema": { "type": "string", "format": "uuid" } }, { "name": "email_id", "in": "query", "required": false, "description": "Equality. Also `email_id[in]=a,b`.", "schema": { "type": "string", "format": "uuid" } }, { "name": "inbox_id", "in": "query", "required": false, "description": "Equality. Also `inbox_id[in]=a,b`.", "schema": { "type": "string", "format": "uuid" } }, { "name": "llm_model", "in": "query", "required": false, "description": "Equality. Also `llm_model[in]=a,b`.", "schema": { "type": "string" } }, { "name": "created_at", "in": "query", "required": false, "description": "Equality. Also `created_at[in]=a,b` and `created_at[gt|gte|lt|lte]`.", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at[gte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at[lte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "finished_at", "in": "query", "required": false, "description": "Equality. Also `finished_at[in]=a,b` and `finished_at[gt|gte|lt|lte]`.", "schema": { "type": "string", "format": "date-time" } }, { "name": "finished_at[gte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "finished_at[lte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "total_cost", "in": "query", "required": false, "description": "Equality. Also `total_cost[in]=a,b` and `total_cost[gt|gte|lt|lte]`.", "schema": { "type": "number" } }, { "name": "total_cost[gte]", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "total_cost[lte]", "in": "query", "required": false, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Page of results.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentRun" } }, "meta": { "type": "object", "required": [ "next_cursor" ], "properties": { "next_cursor": { "type": "string", "nullable": true, "description": "Opaque keyset cursor for the next page; `null` on the last page." } } } } } } } }, "400": { "description": "Body failed Zod validation. `error.details` carries `formErrors`/`fieldErrors`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/agent-runs/{id}": { "get": { "operationId": "get-agent-run", "summary": "Get agent run", "tags": [ "Agent runs" ], "security": [ { "bearerAuth": [ "inbox/agent_runs" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Accepts either the internal UUID or the resource `external_id`.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AgentRun" } } } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/inboxes/{id}/recipients": { "post": { "operationId": "add-allowed-recipient", "summary": "Add allowed recipient", "description": "Accepts either the internal UUID or the resource `external_id`. Adds an email to `allowed_recipients`. Idempotent — returns 200 with the current list when already present.", "tags": [ "Inboxes" ], "security": [ { "bearerAuth": [ "inbox/inboxes", "write" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Accepts either the internal UUID or the resource `external_id`.", "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" } } } } } }, "responses": { "200": { "description": "Recipient already present (no-op).", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "allowed_recipients": { "type": "array", "items": { "type": "string", "format": "email" } } } } } } } } }, "201": { "description": "Recipient added.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "allowed_recipients": { "type": "array", "items": { "type": "string", "format": "email" } } } } } } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "remove-allowed-recipient", "summary": "Remove allowed recipient", "description": "Accepts either the internal UUID or the resource `external_id`. Removes an email from `allowed_recipients`. Accepts the email in JSON body or as the `email` query parameter.", "tags": [ "Inboxes" ], "security": [ { "bearerAuth": [ "inbox/inboxes", "write" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Accepts either the internal UUID or the resource `external_id`.", "schema": { "type": "string", "minLength": 1 } }, { "name": "email", "in": "query", "required": false, "schema": { "type": "string", "format": "email" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" } } } } } }, "responses": { "200": { "description": "Recipient removed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "allowed_recipients": { "type": "array", "items": { "type": "string", "format": "email" } } } } } } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{id}/test": { "post": { "operationId": "send-a-webhook-test-event", "summary": "Send a webhook.ping event", "description": "Accepts either the internal UUID or the resource `external_id`.", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [ "inbox/webhooks", "write" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Optional. 8-255 chars of [A-Za-z0-9_-:.]. A replay with the same key within 24h returns the original response; the same key with a different body returns 409 `conflict`.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } }, { "name": "id", "in": "path", "required": true, "description": "Accepts either the internal UUID or the resource `external_id`.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "202": { "description": "Accepted and queued.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "webhook_id", "event_id", "queued" ], "properties": { "webhook_id": { "type": "string", "format": "uuid" }, "event_id": { "type": "string", "format": "uuid" }, "queued": { "type": "boolean", "enum": [ true ] } } } } } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{id}/regenerate-secret": { "post": { "operationId": "regenerate-the-signing-secret", "summary": "Rotate the signing secret", "description": "Replaces the signing secret and returns the new value **once**. By default the previous secret keeps signing deliveries for 24 hours (`previous_secret_grace_hours`), during which every delivery carries one signature per secret so the receiver can switch keys without dropping events. Pass `0` to revoke the previous secret immediately (leaked secret). Accepts either the internal UUID or the resource `external_id`.", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [ "inbox/webhooks", "write" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Optional. 8-255 chars of [A-Za-z0-9_-:.]. A replay with the same key within 24h returns the original response; the same key with a different body returns 409 `conflict`.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } }, { "name": "id", "in": "path", "required": true, "description": "Accepts either the internal UUID or the resource `external_id`.", "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "signing_secret": { "type": "string", "pattern": "^whsec_[A-Za-z0-9+/]+={0,2}$", "description": "Optional. Bring your own signing secret: `whsec_` + standard base64 of 24-64 random bytes. Generated (32 bytes) when omitted. Returned in plaintext only in this response." }, "previous_secret_grace_hours": { "type": "integer", "minimum": 0, "maximum": 168, "default": 24, "description": "Hours the previous secret remains valid after the rotation. `0` revokes it immediately." } } } } } }, "responses": { "200": { "description": "New signing secret (shown once).", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "signing_secret", "previous_secret_expires_at" ], "properties": { "data": { "$ref": "#/components/schemas/Webhook" }, "signing_secret": { "type": "string", "example": "whsec_..." }, "previous_secret_expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the previous secret stops signing; `null` if revoked immediately." } } } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{id}/deliveries": { "get": { "operationId": "list-webhook-deliveries", "summary": "List webhook deliveries", "description": "Accepts either the internal UUID or the resource `external_id`.", "tags": [ "Webhook deliveries" ], "security": [ { "bearerAuth": [ "inbox/webhooks" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Accepts either the internal UUID or the resource `external_id`.", "schema": { "type": "string", "minLength": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned in `meta.next_cursor` of the previous page.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Comma-separated sort keys, `-` prefix for descending. Allowed: `created_at`, `attempt`, `status`. Default `-created_at`.", "schema": { "type": "string", "default": "-created_at" } }, { "name": "status", "in": "query", "required": false, "description": "Equality. Also `status[in]=a,b`.", "schema": { "type": "string", "enum": [ "pending", "success", "failed" ] } }, { "name": "attempt", "in": "query", "required": false, "description": "Equality. Also `attempt[in]=a,b` and `attempt[gt|gte|lt|lte]`.", "schema": { "type": "integer" } }, { "name": "attempt[gte]", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "attempt[lte]", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "response_status", "in": "query", "required": false, "description": "Equality. Also `response_status[in]=a,b` and `response_status[gt|gte|lt|lte]`.", "schema": { "type": "integer" } }, { "name": "response_status[gte]", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "response_status[lte]", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "system_event_id", "in": "query", "required": false, "description": "Equality. Also `system_event_id[in]=a,b`.", "schema": { "type": "string", "format": "uuid" } }, { "name": "created_at", "in": "query", "required": false, "description": "Equality. Also `created_at[in]=a,b` and `created_at[gt|gte|lt|lte]`.", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at[gte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at[lte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "delivered_at", "in": "query", "required": false, "description": "Equality. Also `delivered_at[in]=a,b` and `delivered_at[gt|gte|lt|lte]`.", "schema": { "type": "string", "format": "date-time" } }, { "name": "delivered_at[gte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "delivered_at[lte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Page of results.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "meta": { "type": "object", "required": [ "next_cursor" ], "properties": { "next_cursor": { "type": "string", "nullable": true, "description": "Opaque keyset cursor for the next page; `null` on the last page." } } } } } } } }, "400": { "description": "Body failed Zod validation. `error.details` carries `formErrors`/`fieldErrors`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{id}/deliveries/{deliveryId}": { "get": { "operationId": "get-webhook-delivery", "summary": "Get webhook delivery", "description": "Accepts either the internal UUID or the resource `external_id`.", "tags": [ "Webhook deliveries" ], "security": [ { "bearerAuth": [ "inbox/webhooks" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Accepts either the internal UUID or the resource `external_id`.", "schema": { "type": "string", "minLength": 1 } }, { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookDelivery" } } } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{id}/deliveries/{deliveryId}/replay": { "post": { "operationId": "replay-a-webhook-delivery", "summary": "Replay a webhook delivery", "description": "Accepts either the internal UUID or the resource `external_id`.", "tags": [ "Webhook deliveries" ], "security": [ { "bearerAuth": [ "inbox/webhooks", "write" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Accepts either the internal UUID or the resource `external_id`.", "schema": { "type": "string", "minLength": 1 } }, { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Accepted and queued.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "webhook_id", "delivery_id", "system_event_id", "queued" ], "properties": { "webhook_id": { "type": "string", "format": "uuid" }, "delivery_id": { "type": "string", "format": "uuid" }, "system_event_id": { "type": "string", "format": "uuid" }, "queued": { "type": "boolean", "enum": [ true ] } } } } } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/system-events": { "get": { "operationId": "list-system-events", "summary": "List system events", "description": "Keyset-paginated. Filters are typed query params (`field=value`, `field[op]=value`); unknown filters, unsortable fields and malformed values are rejected with 400 `validation_failed`.", "tags": [ "System events" ], "security": [ { "bearerAuth": [ "inbox/system_events" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned in `meta.next_cursor` of the previous page.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Comma-separated sort keys, `-` prefix for descending. Allowed: `created_at`, `slug`. Default `-created_at`.", "schema": { "type": "string", "default": "-created_at" } }, { "name": "slug", "in": "query", "required": false, "description": "Equality. Also `slug[in]=a,b`.", "schema": { "type": "string" } }, { "name": "inbox_id", "in": "query", "required": false, "description": "Equality. Also `inbox_id[in]=a,b`.", "schema": { "type": "string", "format": "uuid" } }, { "name": "email_id", "in": "query", "required": false, "description": "Equality. Also `email_id[in]=a,b`.", "schema": { "type": "string", "format": "uuid" } }, { "name": "created_at", "in": "query", "required": false, "description": "Equality. Also `created_at[in]=a,b` and `created_at[gt|gte|lt|lte]`.", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at[gte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at[lte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Page of results.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SystemEvent" } }, "meta": { "type": "object", "required": [ "next_cursor" ], "properties": { "next_cursor": { "type": "string", "nullable": true, "description": "Opaque keyset cursor for the next page; `null` on the last page." } } } } } } } }, "400": { "description": "Body failed Zod validation. `error.details` carries `formErrors`/`fieldErrors`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/system-events/{id}": { "get": { "operationId": "get-system-event", "summary": "Get system event", "tags": [ "System events" ], "security": [ { "bearerAuth": [ "inbox/system_events" ] } ], "parameters": [ { "name": "cloudfront-viewer-mtls-client-cert-fingerprint", "in": "header", "required": true, "description": "mTLS fingerprint. In production CloudFront injects it from viewer mTLS.", "schema": { "type": "string" } }, { "name": "x-origin-shared-secret", "in": "header", "required": false, "description": "Shared secret between CloudFront and the origin. Required in production; ignored in development unless `CF_ORIGIN_SHARED_SECRET` is set.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Accepts either the internal UUID or the resource `external_id`.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SystemEvent" } } } } } }, "401": { "description": "Authentication failed (missing/invalid JWT or mTLS).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but the scope is insufficient or the resource is out of reach.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or filtered out by soft-delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "example": "validation_failed" }, "message": { "type": "string" }, "details": {} } } } }, "Workspace": { "type": "object", "description": "Workspace as returned by the API. `deleted_at` is omitted from responses.", "required": [ "id", "external_id", "source", "label", "slug" ], "properties": { "id": { "type": "string", "format": "uuid" }, "external_id": { "type": "string", "nullable": true }, "source": { "$ref": "#/components/schemas/WorkspaceSource" }, "label": { "type": "string" }, "slug": { "type": "string", "description": "Middle segment of every inbox address under this workspace: \"{organization-slug}.{workspace-slug}.{inbox-slug}@inbox.kobana.com.br\" (the organization segment is omitted when the workspace has none). Unique within the organization. Defaults to the dasherized label." }, "monthly_cost_limit": { "type": "number", "nullable": true }, "monthly_cost_used": { "type": "number" }, "monthly_emails_limit": { "type": "integer", "nullable": true }, "monthly_emails_used": { "type": "integer" }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true, "description": "System metadata, written by Kobana. Read-only." }, "custom_metadata": { "type": "object", "additionalProperties": true, "nullable": true, "description": "User metadata, free-form. Writable through this API." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "WorkspaceSource": { "type": "string", "enum": [ "kobana_app", "kobana_billing", "kobana_inbox", "kobana_agent", "kobana_finance", "kobana_legal", "kobana_team" ] }, "WorkspaceCreate": { "type": "object", "required": [ "source", "label" ], "properties": { "external_id": { "type": "string", "minLength": 1, "description": "Optional. When omitted the server defaults `external_id` to the generated internal `id`." }, "source": { "$ref": "#/components/schemas/WorkspaceSource" }, "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "slug": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "description": "Optional. Lowercase dasherized slug, unique within the organization, used as the middle segment of inbox addresses. Capped at 20 characters so the composed local part fits SMTP's 64-character limit. When omitted, the server derives it from the dasherized `label`." }, "monthly_cost_limit": { "type": "number", "nullable": true, "exclusiveMinimum": 0 }, "monthly_emails_limit": { "type": "integer", "nullable": true, "exclusiveMinimum": 0 }, "custom_metadata": { "type": "object", "additionalProperties": true, "nullable": true, "description": "User metadata, free-form. Send `null` to clear it. Max 64 KB serialized, 16 levels deep." } } }, "WorkspaceUpdate": { "type": "object", "required": [], "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "slug": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "monthly_cost_limit": { "type": "number", "nullable": true, "exclusiveMinimum": 0 }, "monthly_emails_limit": { "type": "integer", "nullable": true, "exclusiveMinimum": 0 }, "custom_metadata": { "type": "object", "additionalProperties": true, "nullable": true, "description": "User metadata, free-form. Send `null` to clear it. Max 64 KB serialized, 16 levels deep." }, "custom_metadata_mode": { "type": "string", "enum": [ "replace", "merge" ], "default": "replace", "description": "How the submitted `custom_metadata` is reconciled with the stored value. `replace` (default) overwrites the whole object; `merge` deep-merges over the current value — nested objects merge recursively, scalars and arrays overwrite the key, and `null` keys are kept (they do not delete the key). Update only." } } }, "Inbox": { "type": "object", "required": [ "id", "external_id", "workspace_id", "label", "slug", "email", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "external_id": { "type": "string", "nullable": true }, "workspace_id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string", "format": "uuid", "nullable": true }, "label": { "type": "string" }, "slug": { "type": "string", "description": "Last segment of the address, unique within the workspace. Frozen after creation: renaming a slug never repoints an address already handed out." }, "email": { "type": "string", "format": "email" }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "allowed_recipients": { "type": "array", "items": { "type": "string", "format": "email" } }, "filters": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "attachments_allow": { "type": "boolean" }, "attachments_max_file_number": { "type": "integer" }, "attachments_max_file_size": { "type": "integer" }, "attachments_max_total_size": { "type": "integer" }, "attachments_allow_rules": { "type": "array", "nullable": true, "maxItems": 20, "description": "Allow list of attachments. An attachment is processed when it matches at least one rule; inside a rule every condition given must match. `null` or `[]` processes every attachment. An attachment outside the list is ignored, never a reason to reject the e-mail: the agent does not see it, the attachment limits do not count it, and a workflow step cannot reference it. On update, omit to keep, send `null` to clear.", "items": { "type": "object", "additionalProperties": false, "properties": { "extensions": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "pattern": "^[A-Za-z0-9]{1,16}$" }, "description": "Extensions without the dot, case-insensitive, e.g. `[\"pdf\", \"xml\"]`." }, "filename_pattern": { "type": "string", "minLength": 1, "maxLength": 200, "description": "JavaScript regular expression tested against the filename, e.g. `^GUIA_`. Nested quantifiers are refused. An attachment without a filename never matches." }, "case_sensitive": { "type": "boolean", "description": "Applies to `filename_pattern`. Default false." } } } }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true, "description": "System metadata, written by Kobana. Read-only." }, "custom_metadata": { "type": "object", "additionalProperties": true, "nullable": true, "description": "User metadata, free-form. Writable through this API." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "InboxCreate": { "type": "object", "required": [ "label" ], "properties": { "external_id": { "type": "string", "minLength": 1, "description": "Optional. Defaults to the generated internal `id`." }, "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "email": { "type": "string", "format": "email", "description": "Optional. Must use the configured inbox domain (`SES_DOMAIN`); otherwise returns 422. Duplicate addresses return 409. When omitted the server composes it as \"{organization-slug}.{workspace-slug}.{inbox-slug}@\"." }, "slug": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "description": "Optional. Lowercase dasherized slug, unique within the workspace, used as the last segment of the address. Returns 409 when it collides with another inbox in the same workspace, and 422 when the composed local part exceeds 64 characters. When omitted, the server derives it from the dasherized `label`." }, "agent_id": { "type": "string", "format": "uuid", "nullable": true }, "allowed_recipients": { "type": "array", "items": { "type": "string", "format": "email" } }, "filters": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "attachments_allow": { "type": "boolean" }, "attachments_max_file_number": { "type": "integer", "exclusiveMinimum": 0 }, "attachments_max_file_size": { "type": "integer", "exclusiveMinimum": 0 }, "attachments_max_total_size": { "type": "integer", "exclusiveMinimum": 0 }, "attachments_allow_rules": { "type": "array", "nullable": true, "maxItems": 20, "description": "Allow list of attachments. An attachment is processed when it matches at least one rule; inside a rule every condition given must match. `null` or `[]` processes every attachment. An attachment outside the list is ignored, never a reason to reject the e-mail: the agent does not see it, the attachment limits do not count it, and a workflow step cannot reference it. On update, omit to keep, send `null` to clear.", "items": { "type": "object", "additionalProperties": false, "properties": { "extensions": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "pattern": "^[A-Za-z0-9]{1,16}$" }, "description": "Extensions without the dot, case-insensitive, e.g. `[\"pdf\", \"xml\"]`." }, "filename_pattern": { "type": "string", "minLength": 1, "maxLength": 200, "description": "JavaScript regular expression tested against the filename, e.g. `^GUIA_`. Nested quantifiers are refused. An attachment without a filename never matches." }, "case_sensitive": { "type": "boolean", "description": "Applies to `filename_pattern`. Default false." } } } }, "custom_metadata": { "type": "object", "additionalProperties": true, "nullable": true, "description": "User metadata, free-form. Send `null` to clear it. Max 64 KB serialized, 16 levels deep." } } }, "InboxUpdate": { "type": "object", "required": [], "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "slug": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "description": "Changing this recomposes the receiving address from the slug chain — mail sent to the previous address stops arriving. Returns 409 on a collision within the workspace, 422 when the composed local part exceeds 64 characters." }, "agent_id": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "allowed_recipients": { "type": "array", "items": { "type": "string", "format": "email" } }, "filters": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "attachments_allow": { "type": "boolean" }, "attachments_max_file_number": { "type": "integer", "exclusiveMinimum": 0 }, "attachments_max_file_size": { "type": "integer", "exclusiveMinimum": 0 }, "attachments_max_total_size": { "type": "integer", "exclusiveMinimum": 0 }, "attachments_allow_rules": { "type": "array", "nullable": true, "maxItems": 20, "description": "Allow list of attachments. An attachment is processed when it matches at least one rule; inside a rule every condition given must match. `null` or `[]` processes every attachment. An attachment outside the list is ignored, never a reason to reject the e-mail: the agent does not see it, the attachment limits do not count it, and a workflow step cannot reference it. On update, omit to keep, send `null` to clear.", "items": { "type": "object", "additionalProperties": false, "properties": { "extensions": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "pattern": "^[A-Za-z0-9]{1,16}$" }, "description": "Extensions without the dot, case-insensitive, e.g. `[\"pdf\", \"xml\"]`." }, "filename_pattern": { "type": "string", "minLength": 1, "maxLength": 200, "description": "JavaScript regular expression tested against the filename, e.g. `^GUIA_`. Nested quantifiers are refused. An attachment without a filename never matches." }, "case_sensitive": { "type": "boolean", "description": "Applies to `filename_pattern`. Default false." } } } }, "custom_metadata": { "type": "object", "additionalProperties": true, "nullable": true, "description": "User metadata, free-form. Send `null` to clear it. Max 64 KB serialized, 16 levels deep." }, "custom_metadata_mode": { "type": "string", "enum": [ "replace", "merge" ], "default": "replace", "description": "How the submitted `custom_metadata` is reconciled with the stored value. `replace` (default) overwrites the whole object; `merge` deep-merges over the current value — nested objects merge recursively, scalars and arrays overwrite the key, and `null` keys are kept (they do not delete the key). Update only." } } }, "EmailBody": { "type": "object", "required": [ "text", "html" ], "properties": { "text": { "type": "string", "nullable": true, "description": "Decoded plain-text body of the message, or null when absent/unparseable." }, "html": { "type": "string", "nullable": true, "description": "Decoded HTML body. Not sanitized — consumers must sanitize before rendering." } } }, "Email": { "type": "object", "required": [ "id", "workspace_id", "inbox_id", "message_id", "from", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "inbox_id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string", "format": "uuid", "nullable": true }, "message_id": { "type": "string" }, "raw_s3_key": { "type": "string" }, "subject": { "type": "string", "nullable": true }, "from": { "type": "string", "format": "email" }, "to": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Envelope recipients (RCPT TO) as delivered by SES. When the message was auto-forwarded this is the inbox address, not the address the sender originally typed." }, "cc": { "type": "array", "items": { "type": "string", "format": "email" } }, "bcc": { "type": "array", "items": { "type": "string", "format": "email" } }, "header_to": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Parsed `To:` header values verbatim. Differs from `to` when the message was forwarded." }, "forwarded": { "type": "boolean", "description": "True when the envelope recipient differs from the `To:` header, or when a forwarder header (Delivered-To, X-Forwarded-To, X-Original-To, Resent-To) is present." }, "forwarded_for": { "type": "string", "format": "email", "nullable": true, "description": "First `To:` header address that is not in the envelope — i.e., the customer-facing address that forwarded to the inbox." }, "status": { "type": "string", "enum": [ "received", "approved", "rejected", "processing", "processed", "failed" ] }, "rejection_reason": { "type": "string", "nullable": true }, "spam_verdict": { "type": "string", "nullable": true }, "virus_verdict": { "type": "string", "nullable": true }, "aws_ses_metadata": { "type": "object", "additionalProperties": true }, "agent_metadata": { "type": "object", "additionalProperties": true }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true, "description": "System metadata, written by Kobana. Read-only." }, "custom_metadata": { "type": "object", "additionalProperties": true, "nullable": true, "description": "User metadata, free-form. Writable through this API." }, "sent_at": { "type": "string", "format": "date-time", "nullable": true }, "processed_at": { "type": "string", "format": "date-time", "nullable": true }, "received_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "body": { "$ref": "#/components/schemas/EmailBody" } } }, "UsageDay": { "type": "object", "required": [ "date", "emails", "tokens", "cost" ], "properties": { "date": { "type": "string", "format": "date", "description": "UTC day." }, "emails": { "type": "integer", "description": "Emails processed (successful agent runs)." }, "tokens": { "type": "integer", "description": "Input + output tokens." }, "cost": { "type": "number", "description": "USD." } } }, "UsageSummary": { "type": "object", "description": "Usage of the caller workspace over a date range, bucketed by UTC day.", "required": [ "range", "totals", "series", "monthly" ], "properties": { "range": { "type": "object", "required": [ "from", "to" ], "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } } }, "totals": { "type": "object", "required": [ "emails", "tokens", "input_tokens", "output_tokens", "cost" ], "properties": { "emails": { "type": "integer" }, "tokens": { "type": "integer" }, "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "cost": { "type": "number", "description": "USD." } } }, "series": { "type": "array", "items": { "$ref": "#/components/schemas/UsageDay" }, "description": "One entry per day in range." }, "monthly": { "type": "object", "description": "Running counters for the current calendar month against the workspace limits (reset on the 1st).", "required": [ "emails_used", "emails_limit", "cost_used", "cost_limit" ], "properties": { "emails_used": { "type": "integer" }, "emails_limit": { "type": "integer", "nullable": true }, "cost_used": { "type": "number" }, "cost_limit": { "type": "number", "nullable": true } } } } }, "UsageCost": { "type": "object", "description": "Cost of the caller workspace split by LLM model.", "required": [ "range", "totals", "models", "by_model", "series" ], "properties": { "range": { "type": "object", "required": [ "from", "to" ], "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } } }, "totals": { "type": "object", "required": [ "cost", "tokens" ], "properties": { "cost": { "type": "number", "description": "USD." }, "tokens": { "type": "integer" } } }, "models": { "type": "array", "items": { "type": "string" }, "description": "Model ids (`provider/model`) that ran in the range." }, "by_model": { "type": "array", "items": { "type": "object", "required": [ "model", "cost", "tokens" ], "properties": { "model": { "type": "string" }, "cost": { "type": "number" }, "tokens": { "type": "integer" } } }, "description": "Totals per model, most expensive first." }, "series": { "type": "array", "items": { "type": "object", "required": [ "date", "by_model" ], "properties": { "date": { "type": "string", "format": "date" }, "by_model": { "type": "object", "additionalProperties": { "type": "number" }, "description": "Cost per model id for that day (USD)." } } } } } }, "Me": { "type": "object", "description": "Identity behind the Bearer token. Never includes the token or anything that identifies it.", "required": [ "user", "organization", "token" ], "properties": { "user": { "type": "object", "nullable": true, "description": "The person behind the token. `null` when the token is not a person's.", "required": [ "id", "name", "email" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "format": "email" } } }, "organization": { "type": "object", "required": [ "id", "name", "external_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "external_id": { "type": "string", "nullable": true } } }, "token": { "type": "object", "required": [ "type", "scopes", "access_level", "expires_at" ], "properties": { "type": { "type": "string", "enum": [ "oauth", "api_key" ], "description": "`oauth` for a token issued through an authorization flow; `api_key` for one created by hand in the authorization server." }, "scopes": { "type": "array", "items": { "type": "string" } }, "access_level": { "type": "string", "enum": [ "read", "write", "all" ] }, "expires_at": { "type": "string", "format": "date-time", "nullable": true } } } } }, "Model": { "type": "object", "description": "An LLM model an agent can use: the AI Gateway catalog narrowed to models with a known price.", "required": [ "id", "provider", "model", "name", "description", "pricing" ], "properties": { "id": { "type": "string", "example": "anthropic/claude-sonnet-5", "description": "Gateway id, `provider/model`. The value accepted in `Agent.llm_model`." }, "provider": { "type": "string" }, "model": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "pricing": { "type": "object", "nullable": true, "description": "USD per token.", "required": [ "input", "output", "cache_read", "cache_write", "valid_from" ], "properties": { "input": { "type": "number" }, "output": { "type": "number" }, "cache_read": { "type": "number" }, "cache_write": { "type": "number" }, "valid_from": { "type": "string", "format": "date-time" } } } } }, "Agent": { "type": "object", "required": [ "id", "external_id", "workspace_id", "label", "llm_model", "system_message" ], "properties": { "id": { "type": "string", "format": "uuid" }, "external_id": { "type": "string", "nullable": true }, "workspace_id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "llm_model": { "type": "string" }, "system_message": { "type": "string" }, "skills_repo": { "type": "string", "format": "uri", "nullable": true }, "version": { "type": "integer", "description": "Current prompt version. Incremented every time `system_message` changes; each version is an immutable snapshot listed at `/agents/{id}/versions`." }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true, "description": "System metadata, written by Kobana. Read-only." }, "custom_metadata": { "type": "object", "additionalProperties": true, "nullable": true, "description": "User metadata, free-form. Writable through this API." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "AgentVersion": { "type": "object", "required": [ "id", "agent_id", "version", "system_message", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string", "format": "uuid" }, "version": { "type": "integer" }, "system_message": { "type": "string", "description": "Prompt snapshot for this version." }, "created_at": { "type": "string", "format": "date-time" } } }, "AgentCreate": { "type": "object", "required": [ "label", "llm_model", "system_message" ], "properties": { "external_id": { "type": "string", "minLength": 1, "description": "Optional. Defaults to the generated internal `id`." }, "label": { "type": "string", "minLength": 1 }, "llm_model": { "type": "string", "minLength": 1 }, "system_message": { "type": "string", "minLength": 1 }, "skills_repo": { "type": "string", "format": "uri", "nullable": true }, "custom_metadata": { "type": "object", "additionalProperties": true, "nullable": true, "description": "User metadata, free-form. Send `null` to clear it. Max 64 KB serialized, 16 levels deep." } } }, "AgentUpdate": { "type": "object", "required": [], "properties": { "label": { "type": "string", "minLength": 1 }, "llm_model": { "type": "string", "minLength": 1 }, "system_message": { "type": "string" }, "skills_repo": { "type": "string", "format": "uri", "nullable": true }, "custom_metadata": { "type": "object", "additionalProperties": true, "nullable": true, "description": "User metadata, free-form. Send `null` to clear it. Max 64 KB serialized, 16 levels deep." }, "custom_metadata_mode": { "type": "string", "enum": [ "replace", "merge" ], "default": "replace", "description": "How the submitted `custom_metadata` is reconciled with the stored value. `replace` (default) overwrites the whole object; `merge` deep-merges over the current value — nested objects merge recursively, scalars and arrays overwrite the key, and `null` keys are kept (they do not delete the key). Update only." } } }, "AgentRun": { "type": "object", "required": [ "id", "workspace_id", "inbox_id", "agent_id", "email_id", "llm_model", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "inbox_id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string", "format": "uuid" }, "email_id": { "type": "string", "format": "uuid" }, "agent_version_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Prompt snapshot the run executed with (see `/agents/{id}/versions`). Null for runs recorded before versioning existed." }, "agent_version": { "type": "integer", "nullable": true, "description": "Agent prompt version number at execution time." }, "llm_model": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "success", "failed" ] }, "error": { "type": "string", "nullable": true }, "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "cache_read": { "type": "integer" }, "cache_write": { "type": "integer" }, "cost_per_token": { "type": "number" }, "total_cost": { "type": "number" }, "duration_ms": { "type": "integer", "nullable": true }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "finished_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Secret": { "type": "object", "description": "A workspace secret. The value is write-only: no endpoint, on any surface, ever returns it.", "required": [ "id", "workspace_id", "key" ], "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "key": { "type": "string", "description": "Identifier a workflow step writes inside `${{secrets.KEY}}`. Uppercase letters, digits and underscores, starting with a letter.", "example": "FINANCE_TOKEN" }, "notes": { "type": "string", "nullable": true }, "last_used_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Last time a workflow step actually interpolated this secret." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SecretCreate": { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,62}$", "example": "FINANCE_TOKEN" }, "value": { "type": "string", "maxLength": 65536, "description": "Stored encrypted; never returned." }, "notes": { "type": "string", "nullable": true } } }, "SecretUpsert": { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,62}$", "description": "Lookup key of the upsert." }, "value": { "type": "string", "maxLength": 65536 }, "notes": { "type": "string", "nullable": true } } }, "SecretUpdate": { "type": "object", "required": [], "properties": { "value": { "type": "string", "maxLength": 65536, "description": "Replaces the stored value." }, "notes": { "type": "string", "nullable": true } } }, "WorkflowStep": { "type": "object", "required": [ "id", "workflow_run_id", "position", "type", "status", "request", "response" ], "properties": { "id": { "type": "string", "format": "uuid" }, "workflow_run_id": { "type": "string", "format": "uuid" }, "position": { "type": "integer", "description": "0-based index in the workflow, also the execution order." }, "type": { "type": "string", "enum": [ "request" ] }, "status": { "type": "string", "enum": [ "pending", "running", "success", "failed", "skipped" ] }, "request": { "type": "object", "required": [ "method", "url", "headers", "body", "form" ], "properties": { "method": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true, "description": "URL as sent, with secret values replaced by `[REDACTED]`." }, "headers": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" } }, "body": { "type": "string", "nullable": true, "description": "Truncated to 4000 characters. A referenced e-mail attachment is shown as `[attachment N: filename, content type, size]`, not as its bytes." }, "form": { "type": "object", "nullable": true, "description": "Multipart fields of a `form` step, as sent. A file field is a `{ attachment, filename, content_type, size }` descriptor of the e-mail attachment that was uploaded.", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "object", "required": [ "attachment", "filename", "content_type", "size" ], "properties": { "attachment": { "type": "integer", "description": "0-based index in the e-mail." }, "filename": { "type": "string" }, "content_type": { "type": "string" }, "size": { "type": "integer", "description": "Bytes." } } } ] } } } }, "response": { "type": "object", "required": [ "status", "headers", "body", "expected_status" ], "properties": { "status": { "type": "integer", "nullable": true }, "headers": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" } }, "body": { "type": "string", "nullable": true, "description": "Truncated to 4000 characters." }, "expected_status": { "type": "integer", "nullable": true, "description": "Status that counts as success. Null means any 2xx." } } }, "error": { "type": "string", "nullable": true }, "duration_ms": { "type": "integer", "nullable": true }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "finished_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "WorkflowRun": { "type": "object", "required": [ "id", "workspace_id", "status", "definition", "summary" ], "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "inbox_id": { "type": "string", "format": "uuid", "nullable": true }, "email_id": { "type": "string", "format": "uuid", "nullable": true }, "agent_id": { "type": "string", "format": "uuid", "nullable": true }, "agent_run_id": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "enum": [ "pending", "running", "success", "failed" ] }, "definition": { "type": "array", "items": { "type": "object" }, "description": "The `workflow` array exactly as the agent returned it, placeholders NOT resolved." }, "summary": { "type": "object", "required": [ "total", "succeeded", "error" ], "properties": { "total": { "type": "integer" }, "succeeded": { "type": "integer" }, "error": { "type": "integer", "description": "Steps that did not succeed (`total - succeeded`): steps that are `failed` plus steps that are `skipped` because they reference one that did not succeed. A run can have several of each." } } }, "error": { "type": "string", "nullable": true, "description": "Set when the run failed: every failed step, one per line, each as `step : `." }, "duration_ms": { "type": "integer", "nullable": true }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "finished_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowStep" }, "description": "Only on `GET /v1/workflow-runs/{id}` — the listing omits them." } } }, "Webhook": { "type": "object", "description": "Webhook record. Secrets never appear in responses: the signing secrets and the encrypted `auth_basic_password`, `auth_bearer_token` and `auth_header_value`. The plaintext `signing_secret` is returned beside `data` exactly once, on create and on rotation.", "required": [ "id", "external_id", "workspace_id", "label", "url", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "external_id": { "type": "string", "nullable": true }, "workspace_id": { "type": "string", "format": "uuid" }, "inbox_id": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "label": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "auth": { "type": "string", "enum": [ "none", "basic", "bearer", "header" ] }, "auth_basic_user": { "type": "string", "nullable": true, "description": "Only when `auth=basic`." }, "auth_header_key": { "type": "string", "nullable": true, "description": "Only when `auth=header`." }, "subscribed_events": { "type": "array", "items": { "type": "string" } }, "consecutive_failures": { "type": "integer" }, "signing_secret_rotated_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the signing secret was last rotated; `null` if never." }, "signing_secret_previous_expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Until when the previous signing secret still signs deliveries after a rotation; `null` when no grace window is open." }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true, "description": "System metadata, written by Kobana. Read-only." }, "custom_metadata": { "type": "object", "additionalProperties": true, "nullable": true, "description": "User metadata, free-form. Writable through this API." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "WebhookCreate": { "type": "object", "required": [ "label", "url" ], "properties": { "external_id": { "type": "string", "minLength": 1, "description": "Optional. Defaults to the generated internal `id`." }, "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "url": { "type": "string", "format": "uri" }, "inbox_id": { "type": "string", "format": "uuid", "nullable": true }, "subscribed_events": { "type": "array", "items": { "type": "string" } }, "auth": { "type": "string", "enum": [ "none", "basic", "bearer", "header" ], "default": "none" }, "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" }, "signing_secret": { "type": "string", "pattern": "^whsec_[A-Za-z0-9+/]+={0,2}$", "description": "Optional. Bring your own signing secret: `whsec_` + standard base64 of 24-64 random bytes. Generated (32 bytes) when omitted. Returned in plaintext only in this response." }, "custom_metadata": { "type": "object", "additionalProperties": true, "nullable": true, "description": "User metadata, free-form. Send `null` to clear it. Max 64 KB serialized, 16 levels deep." } } }, "WebhookUpdate": { "type": "object", "required": [], "properties": { "label": { "type": "string", "minLength": 1 }, "url": { "type": "string", "format": "uri" }, "inbox_id": { "type": "string", "format": "uuid", "nullable": true }, "subscribed_events": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "custom_metadata": { "type": "object", "additionalProperties": true, "nullable": true, "description": "User metadata, free-form. Send `null` to clear it. Max 64 KB serialized, 16 levels deep." }, "custom_metadata_mode": { "type": "string", "enum": [ "replace", "merge" ], "default": "replace", "description": "How the submitted `custom_metadata` is reconciled with the stored value. `replace` (default) overwrites the whole object; `merge` deep-merges over the current value — nested objects merge recursively, scalars and arrays overwrite the key, and `null` keys are kept (they do not delete the key). Update only." } } }, "WebhookDelivery": { "type": "object", "required": [ "id", "webhook_id", "system_event_id", "attempt", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "webhook_id": { "type": "string", "format": "uuid" }, "system_event_id": { "type": "string", "format": "uuid" }, "attempt": { "type": "integer" }, "status": { "type": "string", "enum": [ "pending", "success", "failed" ] }, "request_headers": { "type": "object", "additionalProperties": true }, "request_body": { "type": "object", "additionalProperties": true }, "response_status": { "type": "integer", "nullable": true }, "response_headers": { "type": "object", "additionalProperties": true, "nullable": true }, "response_body": { "type": "string", "nullable": true }, "error": { "type": "string", "nullable": true }, "duration_ms": { "type": "integer", "nullable": true }, "delivered_at": { "type": "string", "format": "date-time", "nullable": true }, "next_retry_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SystemEvent": { "type": "object", "required": [ "id", "workspace_id", "slug", "payload", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "inbox_id": { "type": "string", "format": "uuid", "nullable": true }, "email_id": { "type": "string", "format": "uuid", "nullable": true }, "slug": { "type": "string" }, "payload": { "type": "object", "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "WorkspaceUpsert": { "allOf": [ { "$ref": "#/components/schemas/WorkspaceCreate" }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Match on the internal id. Checked before `external_id`." }, "external_id": { "type": "string", "minLength": 1, "description": "Match on the source-system id. Also stored on the record when it is created." } } } ], "description": "Body of PUT /workspaces: the POST body plus `id` / `external_id` lookup keys." }, "InboxUpsert": { "allOf": [ { "$ref": "#/components/schemas/InboxCreate" }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Match on the internal id. Checked before `external_id`." }, "external_id": { "type": "string", "minLength": 1, "description": "Match on the source-system id. Also stored on the record when it is created." } } } ], "description": "Body of PUT /inboxes: the POST body plus `id` / `external_id` lookup keys." }, "AgentUpsert": { "allOf": [ { "$ref": "#/components/schemas/AgentCreate" }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Match on the internal id. Checked before `external_id`." }, "external_id": { "type": "string", "minLength": 1, "description": "Match on the source-system id. Also stored on the record when it is created." } } } ], "description": "Body of PUT /agents: the POST body plus `id` / `external_id` lookup keys." }, "WebhookUpsert": { "allOf": [ { "$ref": "#/components/schemas/WebhookCreate" }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Match on the internal id. Checked before `external_id`." }, "external_id": { "type": "string", "minLength": 1, "description": "Match on the source-system id. Also stored on the record when it is created." } } } ], "description": "Body of PUT /webhooks: the POST body plus `id` / `external_id` lookup keys." } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "RS256 JWT issued by the Kobana authorization server (`iss` = `https://account[.].kobana.com.br`), verified against the public keys it publishes — this API holds no signing key and cannot mint a token. Claims: `iss`, `aud=https://api.inbox[.].kobana.com.br` (may be a list; the rule is *contains*), `sub`, `jti`, `exp` (required), `scope` (space-separated list), and optional `src` (`user`|`system`). Scopes have two axes: a resource, always prefixed by the app (`inbox/emails`), and a global verb (`write`). A resource without a verb reads; a write needs both (`inbox/emails write`). `inbox/all` is the resource catch-all — it reads every resource and grants no verb. The granular form `inbox/emails:write` satisfies both axes for that resource on its own." } } } }