{ "info": { "name": "Kobana Autonomous Inbox", "description": "Postman collection for the Kobana Autonomous Inbox API.\n\n- **Public API v1**: `/api/v1/*` — Bearer JWT (RS256, issued by the Kobana authorization server) + mTLS terminated at CloudFront. The `Authorization` header is set at the collection level via the `jwt` variable.\n\nVariables to fill in: `baseUrl`, `jwt`, plus the `*_id` resource variables.\n\nResource `[id]` endpoints (workspaces, inboxes, agents, webhooks) accept either the internal UUID or the `external_id` of the resource. POST endpoints that own an `external_id` accept it as an optional field and default it to the internal `id` when omitted. The `deleted_at` field is never returned in API responses or webhook payloads; soft-deleted records are filtered out instead.", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "_postman_id": "kobana-autonomous-inbox-collection" }, "variable": [ { "key": "baseUrl", "value": "http://localhost:3028", "type": "string" }, { "key": "jwt", "value": "", "type": "string", "description": "Bearer JWT (RS256, issued by the Kobana authorization server)." }, { "key": "mtlsFingerprint", "value": "dev-fingerprint-localhost", "type": "string", "description": "Value for cloudfront-viewer-mtls-client-cert-fingerprint; in prod CloudFront injects the real fingerprint." }, { "key": "originSharedSecret", "value": "change-me", "type": "string", "description": "Value for x-origin-shared-secret; must equal CF_ORIGIN_SHARED_SECRET on the server." }, { "key": "workspaceId", "value": "", "type": "string" }, { "key": "inboxId", "value": "", "type": "string" }, { "key": "emailId", "value": "", "type": "string" }, { "key": "agentId", "value": "", "type": "string" }, { "key": "agentRunId", "value": "", "type": "string" }, { "key": "webhookId", "value": "", "type": "string" }, { "key": "deliveryId", "value": "", "type": "string" }, { "key": "systemEventId", "value": "", "type": "string" } ], "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{jwt}}", "type": "string" } ] }, "item": [ { "name": "Public API v1", "description": "All endpoints under `/api/v1`. Requires Bearer JWT and mTLS at CloudFront. Lists return `{ data: [...], meta: { next_cursor } }`.", "item": [ { "name": "Workspaces", "item": [ { "name": "List workspaces", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/api/v1/workspaces?cursor=&limit=25", "host": ["{{baseUrl}}"], "path": ["api", "v1", "workspaces"], "query": [ { "key": "cursor", "value": "" }, { "key": "limit", "value": "25" }, { "key": "source", "value": "", "disabled": true }, { "key": "q", "value": "", "disabled": true } ] }, "header": [ { "key": "cloudfront-viewer-mtls-client-cert-fingerprint", "value": "{{mtlsFingerprint}}", "description": "Dev placeholder — in prod injected by CloudFront viewer mTLS." }, { "key": "x-origin-shared-secret", "value": "{{originSharedSecret}}", "description": "CF_ORIGIN_SHARED_SECRET from the server env. In prod CloudFront injects it." } ] } }, { "name": "Get workspace", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/api/v1/workspaces/{{workspaceId}}", "host": ["{{baseUrl}}"], "path": ["api", "v1", "workspaces", "{{workspaceId}}"] }, "header": [ { "key": "cloudfront-viewer-mtls-client-cert-fingerprint", "value": "{{mtlsFingerprint}}", "description": "Dev placeholder — in prod injected by CloudFront viewer mTLS." }, { "key": "x-origin-shared-secret", "value": "{{originSharedSecret}}", "description": "CF_ORIGIN_SHARED_SECRET from the server env. In prod CloudFront injects it." } ], "description": "The `{id}` path segment accepts either the internal UUID or the resource `external_id`." } }, { "name": "Create workspace", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "cloudfront-viewer-mtls-client-cert-fingerprint", "value": "{{mtlsFingerprint}}", "description": "Dev placeholder — in prod injected by CloudFront viewer mTLS." }, { "key": "x-origin-shared-secret", "value": "{{originSharedSecret}}", "description": "CF_ORIGIN_SHARED_SECRET from the server env. In prod CloudFront injects it." } ], "body": { "mode": "raw", "raw": "{\n \"external_id\": \"{{$guid}}\",\n \"label\": \"New Workspace\",\n \"source\": \"kobana_app\",\n \"slug\": \"new-workspace\",\n \"monthly_cost_limit\": null,\n \"monthly_emails_limit\": null,\n \"custom_metadata\": {}\n}" }, "url": { "raw": "{{baseUrl}}/api/v1/workspaces", "host": ["{{baseUrl}}"], "path": ["api", "v1", "workspaces"] }, "description": "Creates a workspace. `external_id` is optional; when omitted it defaults to the generated internal `id`. `custom_metadata` is an opaque JSON object owned by the API consumer (formerly `user_metadata`)." } }, { "name": "Update workspace", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "cloudfront-viewer-mtls-client-cert-fingerprint", "value": "{{mtlsFingerprint}}", "description": "Dev placeholder — in prod injected by CloudFront viewer mTLS." }, { "key": "x-origin-shared-secret", "value": "{{originSharedSecret}}", "description": "CF_ORIGIN_SHARED_SECRET from the server env. In prod CloudFront injects it." } ], "body": { "mode": "raw", "raw": "{\n \"label\": \"Renamed\",\n \"slug\": \"renamed\",\n \"monthly_cost_limit\": \"100.00\"\n}" }, "url": { "raw": "{{baseUrl}}/api/v1/workspaces/{{workspaceId}}", "host": ["{{baseUrl}}"], "path": ["api", "v1", "workspaces", "{{workspaceId}}"] }, "description": "The `{id}` path segment accepts either the internal UUID or the resource `external_id`." } }, { "name": "Delete workspace", "request": { "method": "DELETE", "url": { "raw": "{{baseUrl}}/api/v1/workspaces/{{workspaceId}}", "host": ["{{baseUrl}}"], "path": ["api", "v1", "workspaces", "{{workspaceId}}"] }, "header": [ { "key": "cloudfront-viewer-mtls-client-cert-fingerprint", "value": "{{mtlsFingerprint}}", "description": "Dev placeholder — in prod injected by CloudFront viewer mTLS." }, { "key": "x-origin-shared-secret", "value": "{{originSharedSecret}}", "description": "CF_ORIGIN_SHARED_SECRET from the server env. In prod CloudFront injects it." } ], "description": "The `{id}` path segment accepts either the internal UUID or the resource `external_id`." } } ] }, { "name": "Inboxes", "item": [ { "name": "List inboxes", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/api/v1/inboxes?cursor=&limit=25", "host": ["{{baseUrl}}"], "path": ["api", "v1", "inboxes"], "query": [ { "key": "cursor", "value": "" }, { "key": "limit", "value": "25" }, { "key": "workspace_id", "value": "", "disabled": true }, { "key": "status", "value": "", "disabled": true } ] }, "header": [ { "key": "cloudfront-viewer-mtls-client-cert-fingerprint", "value": "{{mtlsFingerprint}}", "description": "Dev placeholder — in prod injected by CloudFront viewer mTLS." }, { "key": "x-origin-shared-secret", "value": "{{originSharedSecret}}", "description": "CF_ORIGIN_SHARED_SECRET from the server env. In prod CloudFront injects it." } ] } }, { "name": "Get inbox", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/api/v1/inboxes/{{inboxId}}", "host": ["{{baseUrl}}"], "path": ["api", "v1", "inboxes", "{{inboxId}}"] }, "header": [ { "key": "cloudfront-viewer-mtls-client-cert-fingerprint", "value": "{{mtlsFingerprint}}", "description": "Dev placeholder — in prod injected by CloudFront viewer mTLS." }, { "key": "x-origin-shared-secret", "value": "{{originSharedSecret}}", "description": "CF_ORIGIN_SHARED_SECRET from the server env. In prod CloudFront injects it." } ], "description": "The `{id}` path segment accepts either the internal UUID or the resource `external_id`." } }, { "name": "Create inbox", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "cloudfront-viewer-mtls-client-cert-fingerprint", "value": "{{mtlsFingerprint}}", "description": "Dev placeholder — in prod injected by CloudFront viewer mTLS." }, { "key": "x-origin-shared-secret", "value": "{{originSharedSecret}}", "description": "CF_ORIGIN_SHARED_SECRET from the server env. In prod CloudFront injects it." } ], "body": { "mode": "raw", "raw": "{\n \"external_id\": \"{{$guid}}\",\n \"label\": \"Finance\",\n \"email\": \"finance@inbox.development.kobana.com.br\",\n \"agent_id\": null,\n \"allowed_recipients\": [],\n \"filters\": [],\n \"attachments_allow\": true,\n \"attachments_max_file_number\": 10,\n \"attachments_max_file_size\": 10485760,\n \"attachments_max_total_size\": 26214400,\n \"custom_metadata\": {}\n}" }, "url": { "raw": "{{baseUrl}}/api/v1/inboxes", "host": ["{{baseUrl}}"], "path": ["api", "v1", "inboxes"] }, "description": "Creates an inbox.\n- `external_id` (optional, UUID): defaults to the generated internal `id`.\n- `email` (optional): must use the configured inbox domain (`SES_DOMAIN`); otherwise returns 422. When omitted, the server generates a slug-based local part. Duplicate addresses return 409.\n- `agent_id` (optional): accepts `null` for inboxes that do not run an AI agent.\n- `custom_metadata` (optional): opaque JSON object owned by the API consumer (formerly `user_metadata`)." } }, { "name": "Update inbox", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "cloudfront-viewer-mtls-client-cert-fingerprint", "value": "{{mtlsFingerprint}}", "description": "Dev placeholder — in prod injected by CloudFront viewer mTLS." }, { "key": "x-origin-shared-secret", "value": "{{originSharedSecret}}", "description": "CF_ORIGIN_SHARED_SECRET from the server env. In prod CloudFront injects it." } ], "body": { "mode": "raw", "raw": "{\n \"label\": \"Finance — premium\",\n \"agent_id\": \"{{agentId}}\",\n \"filters\": [\n { \"attribute\": \"subject\", \"operator\": \"contains\", \"value\": \"INVOICE\" }\n ]\n}" }, "url": { "raw": "{{baseUrl}}/api/v1/inboxes/{{inboxId}}", "host": ["{{baseUrl}}"], "path": ["api", "v1", "inboxes", "{{inboxId}}"] }, "description": "The `{id}` path segment accepts either the internal UUID or the resource `external_id`." } }, { "name": "Delete inbox", "request": { "method": "DELETE", "url": { "raw": "{{baseUrl}}/api/v1/inboxes/{{inboxId}}", "host": ["{{baseUrl}}"], "path": ["api", "v1", "inboxes", "{{inboxId}}"] }, "header": [ { "key": "cloudfront-viewer-mtls-client-cert-fingerprint", "value": "{{mtlsFingerprint}}", "description": "Dev placeholder — in prod injected by CloudFront viewer mTLS." }, { "key": "x-origin-shared-secret", "value": "{{originSharedSecret}}", "description": "CF_ORIGIN_SHARED_SECRET from the server env. In prod CloudFront injects it." } ], "description": "The `{id}` path segment accepts either the internal UUID or the resource `external_id`." } }, { "name": "Add allowed recipient", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "cloudfront-viewer-mtls-client-cert-fingerprint", "value": "{{mtlsFingerprint}}", "description": "Dev placeholder — in prod injected by CloudFront viewer mTLS." }, { "key": "x-origin-shared-secret", "value": "{{originSharedSecret}}", "description": "CF_ORIGIN_SHARED_SECRET from the server env. In prod CloudFront injects it." } ], "body": { "mode": "raw", "raw": "{\n \"email\": \"sender@example.com\"\n}" }, "url": { "raw": "{{baseUrl}}/api/v1/inboxes/{{inboxId}}/recipients", "host": ["{{baseUrl}}"], "path": ["api", "v1", "inboxes", "{{inboxId}}", "recipients"] }, "description": "Adds an email to `allowed_recipients`. Idempotent — returns 200 with the current list when already present, 201 when newly added." } }, { "name": "Remove allowed recipient", "request": { "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "cloudfront-viewer-mtls-client-cert-fingerprint", "value": "{{mtlsFingerprint}}", "description": "Dev placeholder — in prod injected by CloudFront viewer mTLS." }, { "key": "x-origin-shared-secret", "value": "{{originSharedSecret}}", "description": "CF_ORIGIN_SHARED_SECRET from the server env. In prod CloudFront injects it." } ], "body": { "mode": "raw", "raw": "{\n \"email\": \"sender@example.com\"\n}" }, "url": { "raw": "{{baseUrl}}/api/v1/inboxes/{{inboxId}}/recipients?email=sender@example.com", "host": ["{{baseUrl}}"], "path": ["api", "v1", "inboxes", "{{inboxId}}", "recipients"], "query": [ { "key": "email", "value": "sender@example.com", "description": "Optional — alternative to JSON body." } ] }, "description": "Removes an email from `allowed_recipients`. Body or `?email=` query both accepted. 404 if the address is not in the list." } } ] }, { "name": "Emails", "description": "Emails only enter via SES ingestion — no POST/PATCH/DELETE direct.", "item": [ { "name": "List emails", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/api/v1/emails?cursor=&limit=25", "host": ["{{baseUrl}}"], "path": ["api", "v1", "emails"], "query": [ { "key": "cursor", "value": "" }, { "key": "limit", "value": "25" }, { "key": "status", "value": "", "disabled": true, "description": "received | approved | rejected | processing | processed | failed" }, { "key": "inbox_id", "value": "", "disabled": true }, { "key": "from", "value": "", "disabled": true }, { "key": "to", "value": "", "disabled": true }, { "key": "received_at[gte]", "value": "", "disabled": true }, { "key": "received_at[lte]", "value": "", "disabled": true }, { "key": "sort", "value": "-received_at", "disabled": true } ] }, "header": [ { "key": "cloudfront-viewer-mtls-client-cert-fingerprint", "value": "{{mtlsFingerprint}}", "description": "Dev placeholder — in prod injected by CloudFront viewer mTLS." }, { "key": "x-origin-shared-secret", "value": "{{originSharedSecret}}", "description": "CF_ORIGIN_SHARED_SECRET from the server env. In prod CloudFront injects it." } ] } }, { "name": "Get email", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/api/v1/emails/{{emailId}}", "host": ["{{baseUrl}}"], "path": ["api", "v1", "emails", "{{emailId}}"] }, "header": [ { "key": "cloudfront-viewer-mtls-client-cert-fingerprint", "value": "{{mtlsFingerprint}}", "description": "Dev placeholder — in prod injected by CloudFront viewer mTLS." }, { "key": "x-origin-shared-secret", "value": "{{originSharedSecret}}", "description": "CF_ORIGIN_SHARED_SECRET from the server env. In prod CloudFront injects it." } ] } }, { "name": "Download .eml", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/api/v1/emails/{{emailId}}/eml", "host": ["{{baseUrl}}"], "path": ["api", "v1", "emails", "{{emailId}}", "eml"] }, "header": [ { "key": "cloudfront-viewer-mtls-client-cert-fingerprint", "value": "{{mtlsFingerprint}}", "description": "Dev placeholder — in prod injected by CloudFront viewer mTLS." }, { "key": "x-origin-shared-secret", "value": "{{originSharedSecret}}", "description": "CF_ORIGIN_SHARED_SECRET from the server env. In prod CloudFront injects it." } ] } }, { "name": "Reprocess email", "request": { "method": "POST", "header": [ { "key": "X-Idempotency-Key", "value": "", "disabled": true }, { "key": "cloudfront-viewer-mtls-client-cert-fingerprint", "value": "{{mtlsFingerprint}}", "description": "Dev placeholder — in prod injected by CloudFront viewer mTLS." }, { "key": "x-origin-shared-secret", "value": "{{originSharedSecret}}", "description": "CF_ORIGIN_SHARED_SECRET from the server env. In prod CloudFront injects it." } ], "url": { "raw": "{{baseUrl}}/api/v1/emails/{{emailId}}/reprocess", "host": ["{{baseUrl}}"], "path": ["api", "v1", "emails", "{{emailId}}", "reprocess"] } } } ] }, { "name": "Agents", "item": [ { "name": "List agents", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/api/v1/agents?cursor=&limit=25", "host": ["{{baseUrl}}"], "path": ["api", "v1", "agents"], "query": [ { "key": "cursor", "value": "" }, { "key": "limit", "value": "25" } ] }, "header": [ { "key": "cloudfront-viewer-mtls-client-cert-fingerprint", "value": "{{mtlsFingerprint}}", "description": "Dev placeholder — in prod injected by CloudFront viewer mTLS." }, { "key": "x-origin-shared-secret", "value": "{{originSharedSecret}}", "description": "CF_ORIGIN_SHARED_SECRET from the server env. In prod CloudFront injects it." } ] } }, { "name": "Get agent", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/api/v1/agents/{{agentId}}", "host": ["{{baseUrl}}"], "path": ["api", "v1", "agents", "{{agentId}}"] }, "header": [ { "key": "cloudfront-viewer-mtls-client-cert-fingerprint", "value": "{{mtlsFingerprint}}", "description": "Dev placeholder — in prod injected by CloudFront viewer mTLS." }, { "key": "x-origin-shared-secret", "value": "{{originSharedSecret}}", "description": "CF_ORIGIN_SHARED_SECRET from the server env. In prod CloudFront injects it." } ], "description": "The `{id}` path segment accepts either the internal UUID or the resource `external_id`." } }, { "name": "Create agent", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "cloudfront-viewer-mtls-client-cert-fingerprint", "value": "{{mtlsFingerprint}}", "description": "Dev placeholder — in prod injected by CloudFront viewer mTLS." }, { "key": "x-origin-shared-secret", "value": "{{originSharedSecret}}", "description": "CF_ORIGIN_SHARED_SECRET from the server env. In prod CloudFront injects it." } ], "body": { "mode": "raw", "raw": "{\n \"external_id\": \"{{$guid}}\",\n \"label\": \"Triage\",\n \"llm_model\": \"anthropic/claude-haiku-4-5\",\n \"system_message\": \"You are a triage agent.\",\n \"skills_repo\": \"https://github.com/kobana/skills-triage.git\"\n}" }, "url": { "raw": "{{baseUrl}}/api/v1/agents", "host": ["{{baseUrl}}"], "path": ["api", "v1", "agents"] }, "description": "Creates an agent. `external_id` is optional; when omitted it defaults to the generated internal `id`." } }, { "name": "Update agent", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "cloudfront-viewer-mtls-client-cert-fingerprint", "value": "{{mtlsFingerprint}}", "description": "Dev placeholder — in prod injected by CloudFront viewer mTLS." }, { "key": "x-origin-shared-secret", "value": "{{originSharedSecret}}", "description": "CF_ORIGIN_SHARED_SECRET from the server env. In prod CloudFront injects it." } ], "body": { "mode": "raw", "raw": "{\n \"llm_model\": \"anthropic/claude-sonnet-4-5\",\n \"system_message\": \"Updated prompt.\"\n}" }, "url": { "raw": "{{baseUrl}}/api/v1/agents/{{agentId}}", "host": ["{{baseUrl}}"], "path": ["api", "v1", "agents", "{{agentId}}"] }, "description": "The `{id}` path segment accepts either the internal UUID or the resource `external_id`." } }, { "name": "Delete agent", "request": { "method": "DELETE", "url": { "raw": "{{baseUrl}}/api/v1/agents/{{agentId}}", "host": ["{{baseUrl}}"], "path": ["api", "v1", "agents", "{{agentId}}"] }, "header": [ { "key": "cloudfront-viewer-mtls-client-cert-fingerprint", "value": "{{mtlsFingerprint}}", "description": "Dev placeholder — in prod injected by CloudFront viewer mTLS." }, { "key": "x-origin-shared-secret", "value": "{{originSharedSecret}}", "description": "CF_ORIGIN_SHARED_SECRET from the server env. In prod CloudFront injects it." } ], "description": "The `{id}` path segment accepts either the internal UUID or the resource `external_id`." } } ] }, { "name": "Agent Runs", "description": "Read-only audit of agent executions.", "item": [ { "name": "List agent runs", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/api/v1/agent-runs?cursor=&limit=25", "host": ["{{baseUrl}}"], "path": ["api", "v1", "agent-runs"], "query": [ { "key": "cursor", "value": "" }, { "key": "limit", "value": "25" }, { "key": "agent_id", "value": "", "disabled": true }, { "key": "inbox_id", "value": "", "disabled": true }, { "key": "email_id", "value": "", "disabled": true }, { "key": "status", "value": "", "disabled": true }, { "key": "started_at[gte]", "value": "", "disabled": true }, { "key": "started_at[lte]", "value": "", "disabled": true } ] }, "header": [ { "key": "cloudfront-viewer-mtls-client-cert-fingerprint", "value": "{{mtlsFingerprint}}", "description": "Dev placeholder — in prod injected by CloudFront viewer mTLS." }, { "key": "x-origin-shared-secret", "value": "{{originSharedSecret}}", "description": "CF_ORIGIN_SHARED_SECRET from the server env. In prod CloudFront injects it." } ] } } ] }, { "name": "Webhooks", "item": [ { "name": "List webhooks", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/api/v1/webhooks?cursor=&limit=25", "host": ["{{baseUrl}}"], "path": ["api", "v1", "webhooks"], "query": [ { "key": "cursor", "value": "" }, { "key": "limit", "value": "25" }, { "key": "inbox_id", "value": "", "disabled": true } ] }, "header": [ { "key": "cloudfront-viewer-mtls-client-cert-fingerprint", "value": "{{mtlsFingerprint}}", "description": "Dev placeholder — in prod injected by CloudFront viewer mTLS." }, { "key": "x-origin-shared-secret", "value": "{{originSharedSecret}}", "description": "CF_ORIGIN_SHARED_SECRET from the server env. In prod CloudFront injects it." } ] } }, { "name": "Get webhook", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/api/v1/webhooks/{{webhookId}}", "host": ["{{baseUrl}}"], "path": ["api", "v1", "webhooks", "{{webhookId}}"] }, "header": [ { "key": "cloudfront-viewer-mtls-client-cert-fingerprint", "value": "{{mtlsFingerprint}}", "description": "Dev placeholder — in prod injected by CloudFront viewer mTLS." }, { "key": "x-origin-shared-secret", "value": "{{originSharedSecret}}", "description": "CF_ORIGIN_SHARED_SECRET from the server env. In prod CloudFront injects it." } ], "description": "The `{id}` path segment accepts either the internal UUID or the resource `external_id`." } }, { "name": "Create webhook", "description": "Returns `signing_secret` in plaintext **once**.", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "cloudfront-viewer-mtls-client-cert-fingerprint", "value": "{{mtlsFingerprint}}", "description": "Dev placeholder — in prod injected by CloudFront viewer mTLS." }, { "key": "x-origin-shared-secret", "value": "{{originSharedSecret}}", "description": "CF_ORIGIN_SHARED_SECRET from the server env. In prod CloudFront injects it." } ], "body": { "mode": "raw", "raw": "{\n \"external_id\": \"{{$guid}}\",\n \"label\": \"Local listener\",\n \"url\": \"https://example.com/webhook\",\n \"inbox_id\": \"{{inboxId}}\",\n \"subscribed_events\": [\n \"email.db.created\",\n \"email.agent.processed\"\n ]\n}" }, "url": { "raw": "{{baseUrl}}/api/v1/webhooks", "host": ["{{baseUrl}}"], "path": ["api", "v1", "webhooks"] }, "description": "Creates a webhook subscription. `external_id` is optional; when omitted it defaults to the generated internal `id`. Webhook delivery bodies share the API serializer (snake_case keys, no `deleted_at`); the original `SystemEvent.payload` is exposed as the opaque `data` field." } }, { "name": "Update webhook", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "cloudfront-viewer-mtls-client-cert-fingerprint", "value": "{{mtlsFingerprint}}", "description": "Dev placeholder — in prod injected by CloudFront viewer mTLS." }, { "key": "x-origin-shared-secret", "value": "{{originSharedSecret}}", "description": "CF_ORIGIN_SHARED_SECRET from the server env. In prod CloudFront injects it." } ], "body": { "mode": "raw", "raw": "{\n \"label\": \"Production listener\",\n \"subscribed_events\": [\"email.db.created\"]\n}" }, "url": { "raw": "{{baseUrl}}/api/v1/webhooks/{{webhookId}}", "host": ["{{baseUrl}}"], "path": ["api", "v1", "webhooks", "{{webhookId}}"] }, "description": "The `{id}` path segment accepts either the internal UUID or the resource `external_id`." } }, { "name": "Delete webhook", "request": { "method": "DELETE", "url": { "raw": "{{baseUrl}}/api/v1/webhooks/{{webhookId}}", "host": ["{{baseUrl}}"], "path": ["api", "v1", "webhooks", "{{webhookId}}"] }, "header": [ { "key": "cloudfront-viewer-mtls-client-cert-fingerprint", "value": "{{mtlsFingerprint}}", "description": "Dev placeholder — in prod injected by CloudFront viewer mTLS." }, { "key": "x-origin-shared-secret", "value": "{{originSharedSecret}}", "description": "CF_ORIGIN_SHARED_SECRET from the server env. In prod CloudFront injects it." } ], "description": "The `{id}` path segment accepts either the internal UUID or the resource `external_id`." } }, { "name": "Test webhook", "description": "Dispatches a synthetic `webhook.test` event.", "request": { "method": "POST", "url": { "raw": "{{baseUrl}}/api/v1/webhooks/{{webhookId}}/test", "host": ["{{baseUrl}}"], "path": ["api", "v1", "webhooks", "{{webhookId}}", "test"] }, "header": [ { "key": "cloudfront-viewer-mtls-client-cert-fingerprint", "value": "{{mtlsFingerprint}}", "description": "Dev placeholder — in prod injected by CloudFront viewer mTLS." }, { "key": "x-origin-shared-secret", "value": "{{originSharedSecret}}", "description": "CF_ORIGIN_SHARED_SECRET from the server env. In prod CloudFront injects it." } ], "description": "The `{id}` path segment accepts either the internal UUID or the resource `external_id`." } }, { "name": "Regenerate signing secret", "description": "Returns the new secret in plaintext **once**; invalidates the previous one.", "request": { "method": "POST", "url": { "raw": "{{baseUrl}}/api/v1/webhooks/{{webhookId}}/regenerate-secret", "host": ["{{baseUrl}}"], "path": ["api", "v1", "webhooks", "{{webhookId}}", "regenerate-secret"] }, "header": [ { "key": "cloudfront-viewer-mtls-client-cert-fingerprint", "value": "{{mtlsFingerprint}}", "description": "Dev placeholder — in prod injected by CloudFront viewer mTLS." }, { "key": "x-origin-shared-secret", "value": "{{originSharedSecret}}", "description": "CF_ORIGIN_SHARED_SECRET from the server env. In prod CloudFront injects it." } ], "description": "The `{id}` path segment accepts either the internal UUID or the resource `external_id`." } } ] }, { "name": "Webhook Deliveries", "item": [ { "name": "List deliveries", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/api/v1/webhooks/{{webhookId}}/deliveries?cursor=&limit=25", "host": ["{{baseUrl}}"], "path": ["api", "v1", "webhooks", "{{webhookId}}", "deliveries"], "query": [ { "key": "cursor", "value": "" }, { "key": "limit", "value": "25" }, { "key": "status", "value": "", "disabled": true, "description": "pending | succeeded | failed | dead" }, { "key": "attempt", "value": "", "disabled": true }, { "key": "created_at[gte]", "value": "", "disabled": true } ] }, "header": [ { "key": "cloudfront-viewer-mtls-client-cert-fingerprint", "value": "{{mtlsFingerprint}}", "description": "Dev placeholder — in prod injected by CloudFront viewer mTLS." }, { "key": "x-origin-shared-secret", "value": "{{originSharedSecret}}", "description": "CF_ORIGIN_SHARED_SECRET from the server env. In prod CloudFront injects it." } ] } }, { "name": "Get delivery", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/api/v1/webhooks/{{webhookId}}/deliveries/{{deliveryId}}", "host": ["{{baseUrl}}"], "path": ["api", "v1", "webhooks", "{{webhookId}}", "deliveries", "{{deliveryId}}"] }, "header": [ { "key": "cloudfront-viewer-mtls-client-cert-fingerprint", "value": "{{mtlsFingerprint}}", "description": "Dev placeholder — in prod injected by CloudFront viewer mTLS." }, { "key": "x-origin-shared-secret", "value": "{{originSharedSecret}}", "description": "CF_ORIGIN_SHARED_SECRET from the server env. In prod CloudFront injects it." } ] } }, { "name": "Replay delivery", "description": "Re-enqueues immediately, ignoring backoff.", "request": { "method": "POST", "url": { "raw": "{{baseUrl}}/api/v1/webhooks/{{webhookId}}/deliveries/{{deliveryId}}/replay", "host": ["{{baseUrl}}"], "path": [ "api", "v1", "webhooks", "{{webhookId}}", "deliveries", "{{deliveryId}}", "replay" ] }, "header": [ { "key": "cloudfront-viewer-mtls-client-cert-fingerprint", "value": "{{mtlsFingerprint}}", "description": "Dev placeholder — in prod injected by CloudFront viewer mTLS." }, { "key": "x-origin-shared-secret", "value": "{{originSharedSecret}}", "description": "CF_ORIGIN_SHARED_SECRET from the server env. In prod CloudFront injects it." } ] } } ] }, { "name": "System Events", "description": "Read-only event audit trail.", "item": [ { "name": "List system events", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/api/v1/system-events?cursor=&limit=25", "host": ["{{baseUrl}}"], "path": ["api", "v1", "system-events"], "query": [ { "key": "cursor", "value": "" }, { "key": "limit", "value": "25" }, { "key": "slug", "value": "", "disabled": true }, { "key": "inbox_id", "value": "", "disabled": true }, { "key": "email_id", "value": "", "disabled": true }, { "key": "created_at[gte]", "value": "", "disabled": true }, { "key": "created_at[lte]", "value": "", "disabled": true } ] }, "header": [ { "key": "cloudfront-viewer-mtls-client-cert-fingerprint", "value": "{{mtlsFingerprint}}", "description": "Dev placeholder — in prod injected by CloudFront viewer mTLS." }, { "key": "x-origin-shared-secret", "value": "{{originSharedSecret}}", "description": "CF_ORIGIN_SHARED_SECRET from the server env. In prod CloudFront injects it." } ] } } ] }, { "name": "Docs", "auth": { "type": "noauth" }, "item": [ { "name": "OpenAPI JSON", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/api/v1/openapi.json", "host": ["{{baseUrl}}"], "path": ["api", "v1", "openapi.json"] }, "header": [ { "key": "cloudfront-viewer-mtls-client-cert-fingerprint", "value": "{{mtlsFingerprint}}", "description": "Dev placeholder — in prod injected by CloudFront viewer mTLS." }, { "key": "x-origin-shared-secret", "value": "{{originSharedSecret}}", "description": "CF_ORIGIN_SHARED_SECRET from the server env. In prod CloudFront injects it." } ] } }, { "name": "Swagger UI", "request": { "method": "GET", "url": { "raw": "{{baseUrl}}/api/v1/docs", "host": ["{{baseUrl}}"], "path": ["api", "v1", "docs"] }, "header": [ { "key": "cloudfront-viewer-mtls-client-cert-fingerprint", "value": "{{mtlsFingerprint}}", "description": "Dev placeholder — in prod injected by CloudFront viewer mTLS." }, { "key": "x-origin-shared-secret", "value": "{{originSharedSecret}}", "description": "CF_ORIGIN_SHARED_SECRET from the server env. In prod CloudFront injects it." } ] } } ] } ] } ] }