Introduction

Autonomous Inbox is a service that receives, stores, filters and processes inbound email on behalf of Kobana's internal products. Email arrives via AWS SES, is persisted to S3 and Postgres, optionally processed by an LLM agent, and surfaced through a public REST API and webhooks.

The API is REST over HTTPS, with JSON and mTLS + Bearer JWT authentication. Everything the platform does with workspaces, inboxes, emails, agents and webhooks is available to your systems, under the same workspace isolation as the product itself.

Getting started

1. Get a client certificate and a JWT for the target environment — see Authentication.

2. Make your first call:

   curl https://api.inbox.kobana.com.br/v1/workspaces?limit=1 \
     --cert ./client.crt --key ./client.key \
     -H "Authorization: Bearer $JWT" \
     -H "Accept: application/json"

3. Explore the resources — the Resources category in the sidebar documents every endpoint with examples. Or import the OpenAPI specification / the Postman collection.

Format

The API accepts and returns JSON only. All requests must use Content-Type: application/json. All responses use snake_case.

Field type	Format
DateTime	ISO 8601 in UTC with millisecond precision. Example: 2026-05-17T12:34:56.789Z
UUID	Resource identifiers are UUID v4

Conventions used in this documentation

Convention	Meaning
{id}	Path variable to be replaced in a URL.
...	Response content truncated for readability.
$JWT	Your Bearer token. For command-line testing, export it: export JWT=xxxxxxxxxxxxxxxxxxxxxxxx and paste the commands from this documentation into your terminal.

Status codes

The API returns standard HTTP codes:

	Code	Meaning
✅	200 OK	Successful request with a response body.
✅	201 Created	Resource created successfully.
✅	202 Accepted	Request accepted for asynchronous processing.
✅	204 No Content	Successful request, no response body.
❌	400 Bad Request	Malformed request.
❌	401 Unauthorized	Missing or invalid client certificate / JWT.
❌	403 Forbidden	Authenticated but lacking the required scope.
❌	404 Not Found	Resource does not exist, or belongs to another workspace.
❌	409 Conflict	State conflict — e.g. external_id already in use, X-Idempotency-Key reused with a different body.
❌	422 Unprocessable Entity	Well-formed request, invalid data.
❌	429 Too Many Requests	Rate limit exceeded.
❌	500 Internal Server Error	Unhandled error. See server status.

The error envelope and the stable vocabulary of error codes are documented in Errors.

Request correlation

Every response — successful or not — carries an X-Request-Id header. Include it when reporting issues so the Kobana team can pull the trace from OpenTelemetry.

Next steps

• Authentication — mTLS, JWT, scopes.
• Endpoints — the API and documentation hosts.
• OpenAPI — OpenAPI 3.1 spec for download or live.
• User-Agent — header to identify your integration.
• Rate limiting — throttling and response headers.
• Pagination — cursor pagination and the list envelope.
• Filtering and sorting — query parameter grammar.
• Idempotency — X-Idempotency-Key for safe retries.
• Errors — error envelope and code vocabulary.
• Data retention — retention policy by resource.