K8 HQ Content API

Two ways in, one API:

- **API tokens** (scripts, AI agents, integrations) use https://api.k8hq.com/v1 with Authorization: Bearer k8hq_.... A token belongs to one project, acts for a member with that member's current access, can be narrowed to some inboxes, and has scopes: messages:read, content:read, flags:write, send. K8 HQ staff issue tokens for now.

- **The K8 HQ web app** uses https://app.k8hq.com/api/v1 with a session from signing in with a passkey.

Message content is encrypted at rest. Metadata (sender, subject, flags) comes back in plain JSON. With content:read, a token can read a message decrypted (/content, /source, /attachments/{n}) from inboxes in compatible mode, where K8 HQ's servers can open them; each such read is recorded in the inbox's audit log. Zero-access inboxes, and the web app, get ciphertext only (/raw), opened with keys sealed to the user's own key (/keys).

Responses that never change (/raw) may be kept by the browser; message metadata carries an ETag to revalidate. Shared caches never store responses.

Errors are JSON objects with one field, error. Inboxes you have no access to, and messages or labels that aren't in the inbox, return 404.

Authentication

Base URL	For
`https://api.k8hq.com/v1`	API tokens
`https://app.k8hq.com/api/v1`	The K8 HQ web app (sessions)

curl -H "Authorization: Bearer $K8HQ_TOKEN" https://api.k8hq.com/v1/inboxes

Endpoints

List your inboxes
Get the inbox's keys
List labels
List a label's messages
Get a message
Change a message's flags
Get a message's encrypted content
Get an attachment (decrypted)
Read a message (decrypted)
Get a message's source (decrypted)
Get what's needed to send
Send a message (plaintext)
Send a message
List event types
Register an event type
Read the project's events
Publish an event
Stream inbox changes

Inboxes

List your inboxes

GET/inboxes

The inboxes you've been granted access to, with your role in each.

For API tokens with messages:read and the web app.

Response body (JSON)

Field	Type	Description
`inboxes` required	InboxGrant[]

Responses

Status	Body	Meaning
200	JSON	Your inboxes.
401	Error	No token, or it expired: sign in again.
403	Error	The token lacks the scope, or (decrypted content) the inbox is zero-access, or the caller is a web session.

Get the inbox's keys

GET/inboxes/{inbox}/keys

Every epoch key of the inbox, each sealed to your user key, which you set up in the web app. Messages name the epoch they were encrypted under (keyEpoch).

For API tokens with messages:read and the web app.

Parameters

Name	Type	Description
`inbox (path)` required	string	Inbox ID (`ibx_…`).

Response body (JSON)

Field	Type	Description
`epochs` required	object[]

Responses

Status	Body	Meaning
200	JSON	The sealed epoch keys.
401	Error	No token, or it expired: sign in again.
403	Error	The token lacks the scope, or (decrypted content) the inbox is zero-access, or the caller is a web session.
404	Error	Not found, or not yours.
409	Error	You haven't set up your encryption key yet.

List labels

GET/inboxes/{inbox}/labels

The inbox's labels (folders in a mail app): INBOX first, then special-use labels (Sent, Drafts, Trash, Spam, Archive), then the rest by name. A message can carry several labels.

For API tokens with messages:read and the web app.

Parameters

Name	Type	Description
`inbox (path)` required	string	Inbox ID (`ibx_…`).

Response body (JSON)

Field	Type	Description
`labels` required	Label[]

Responses

Status	Body	Meaning
200	JSON	The labels.
401	Error	No token, or it expired: sign in again.
403	Error	The token lacks the scope, or (decrypted content) the inbox is zero-access, or the caller is a web session.
404	Error	Not found, or not yours.

Messages

List a label's messages

GET/inboxes/{inbox}/labels/{label}/messages

Newest first. To get the next page, pass the response's before back as before; it's absent on the last page.

For API tokens with messages:read and the web app.

Parameters

Name	Type	Description
`inbox (path)` required	string	Inbox ID (`ibx_…`).
`label (path)` required	string	Label ID (`lbl_…`).
`limit (query)`	integer	Page size, 1 to 100.
`before (query)`	integer	Only messages with a lower UID than this (a cursor from the previous page).

Response body (JSON)

Field	Type	Description
`messages` required	MessageSummary[]
`before`	integer	Cursor for the next page.

Responses

Status	Body	Meaning
200	JSON	One page of messages.
401	Error	No token, or it expired: sign in again.
403	Error	The token lacks the scope, or (decrypted content) the inbox is zero-access, or the caller is a web session.
404	Error	Not found, or not yours.

Get a message

GET/inboxes/{inbox}/messages/{msg}

Metadata plus the message's data key, wrapped to the inbox epoch key. The body comes from /raw. The response carries an ETag (it changes with any change to the message, including data added later) and Cache-Control: private, no-cache: send If-None-Match to get 304 when nothing changed.

For API tokens with messages:read and the web app.

Parameters

Name	Type	Description
`inbox (path)` required	string	Inbox ID (`ibx_…`).
`msg (path)` required	string	Message ID (`msg_…`).
`If-None-Match (header)`	string	The ETag of a copy you have.

Response body (JSON)

Field	Type	Description
`keyEpoch` required	integer	The inbox epoch the message was encrypted under.
`message` required	MessageSummary
`wrappedDek` required	string	The message's data key, sealed to the epoch key.
`cc`	string
`inReplyTo`	string
`messageId`	string	The Message-ID header.
`replyTo`	string

Responses

Status	Body	Meaning
200	JSON	The message.
304		Not modified: your copy is current.
401	Error	No token, or it expired: sign in again.
403	Error	The token lacks the scope, or (decrypted content) the inbox is zero-access, or the caller is a web session.
404	Error	Not found, or not yours.

Change a message's flags

POST/inboxes/{inbox}/messages/{msg}/flags

Adds and removes flags by their neutral names. Mail apps connected over IMAP, and other open web app tabs, see the change right away. Other flags (draft, junk, ...) are set by mail apps.

For API tokens with flags:write and the web app.

Parameters

Name	Type	Description
`inbox (path)` required	string	Inbox ID (`ibx_…`).
`msg (path)` required	string	Message ID (`msg_…`).

Request body (JSON)

Field	Type	Description
`add`	WebFlag[]
`remove`	WebFlag[]

{"add":["seen"]}

Response body (JSON)

Field	Type	Description
`flags` required	Flag[]

Responses

Status	Body	Meaning
200	JSON	The message's flags after the change.
400	Error	The request is malformed.
401	Error	No token, or it expired: sign in again.
403	Error	The token lacks the scope, or (decrypted content) the inbox is zero-access, or the caller is a web session.
404	Error	Not found, or not yours.

Get a message's encrypted content

GET/inboxes/{inbox}/messages/{msg}/raw

The encrypted RFC 5322 message exactly as stored. Decrypt it with the data key from GET /inboxes/{inbox}/messages/{msg}. Messages never change, so the response may be kept by the browser indefinitely (Cache-Control: private, max-age=31536000, immutable).

For API tokens with messages:read and the web app.

Parameters

Name	Type	Description
`inbox (path)` required	string	Inbox ID (`ibx_…`).
`msg (path)` required	string	Message ID (`msg_…`).

Responses

Status	Body	Meaning
200	application/octet-stream	Ciphertext.
401	Error	No token, or it expired: sign in again.
403	Error	The token lacks the scope, or (decrypted content) the inbox is zero-access, or the caller is a web session.
404	Error	Not found, or not yours.

Content

Get an attachment (decrypted)

GET/inboxes/{inbox}/messages/{msg}/attachments/{n}

One attachment or inline part, with its content type and filename. Compatible-mode inboxes only; audited. Never cached.

For API tokens with content:read.

Parameters

Name	Type	Description
`inbox (path)` required	string	Inbox ID (`ibx_…`).
`msg (path)` required	string	Message ID (`msg_…`).
`n (path)` required	integer	The attachment's `index` from `/content`.

Responses

Status	Body	Meaning
200	application/octet-stream	The attachment.
401	Error	No token, or it expired: sign in again.
403	Error	The token lacks the scope, or (decrypted content) the inbox is zero-access, or the caller is a web session.
404	Error	Not found, or not yours.

Read a message (decrypted)

GET/inboxes/{inbox}/messages/{msg}/content

The message decrypted and parsed: headers, the text and HTML bodies, and its attachments and inline parts (fetch each by index). Compatible-mode inboxes only; the read is recorded in the inbox's audit log (access.content.read). Never cached.

For API tokens with content:read.

Parameters

Name	Type	Description
`inbox (path)` required	string	Inbox ID (`ibx_…`).
`msg (path)` required	string	Message ID (`msg_…`).

Response body (JSON)

Field	Type	Description
`attachments` required	Attachment[]
`flags` required	Flag[]
`headers` required	object	Decoded headers: from, to, cc, replyTo, subject, date, messageId, inReplyTo, references (those present).
`html` required	string	The HTML body (empty if none). Untrusted: sanitize before display.
`id` required	string
`receivedAt` required	string
`text` required	string	The plain-text body (empty if none).
`keywords`	string[]

Responses

Status	Body	Meaning
200	JSON	The message.
401	Error	No token, or it expired: sign in again.
403	Error	The token lacks the scope, or (decrypted content) the inbox is zero-access, or the caller is a web session.
404	Error	Not found, or not yours.
422	Error	The message couldn't be parsed; read it whole from /source.

Get a message's source (decrypted)

GET/inboxes/{inbox}/messages/{msg}/source

The whole RFC 5322 message, decrypted. Compatible-mode inboxes only; audited like /content. Never cached.

For API tokens with content:read.

Parameters

Name	Type	Description
`inbox (path)` required	string	Inbox ID (`ibx_…`).
`msg (path)` required	string	Message ID (`msg_…`).

Responses

Status	Body	Meaning
200	message/rfc822	The message.
401	Error	No token, or it expired: sign in again.
403	Error	The token lacks the scope, or (decrypted content) the inbox is zero-access, or the caller is a web session.
404	Error	Not found, or not yours.

Sending

Get what's needed to send

GET/inboxes/{inbox}/compose

The addresses the inbox receives on and the current epoch public key to seal outgoing messages to.

For API tokens with send and the web app.

Parameters

Name	Type	Description
`inbox (path)` required	string	Inbox ID (`ibx_…`).

Response body (JSON)

Field	Type	Description
`addresses` required	string[]
`epoch` required	integer
`epochPublic` required	string	The epoch's X25519 public key.

Responses

Status	Body	Meaning
200	JSON	Addresses and the sealing key.
401	Error	No token, or it expired: sign in again.
403	Error	The token lacks the scope, or (decrypted content) the inbox is zero-access, or the caller is a web session.
404	Error	Not found, or not yours.

Send a message (plaintext)

POST/inboxes/{inbox}/messages

Sends an RFC 5322 message as given: the same checks and limits as sending from a mail app, and a copy is filed in Sent. For API tokens; the web app seals its messages (/send). Up to 100 recipients and 25 MB.

For API tokens with send.

Parameters

Name	Type	Description
`inbox (path)` required	string	Inbox ID (`ibx_…`).

Request body (JSON)

Field	Type	Description
`from` required	string	A bare address the inbox may send as; it must match the message's From header.
`raw` required	string	The RFC 5322 message.
`to` required	string[]	Every recipient (To, Cc and Bcc), as bare addresses.

Response body (JSON)

Field	Type	Description
`sent` required	true

Responses

Status	Body	Meaning
200	JSON	Accepted for delivery.
400	Error	The request is malformed.
401	Error	No token, or it expired: sign in again.
403	Error	The inbox can't send as `from`.
404	Error	Not found, or not yours.
422	Error	Refused: a sending limit or policy, with the reason.
503	Error	Temporary failure; try again later.

Send a message

POST/inboxes/{inbox}/send

Sends a message the client sealed to the inbox's epoch key, bound to a draft ID. It goes through the same checks and limits as sending from a mail app, and a copy is filed in Sent. Up to 100 recipients and 25 MB.

For API tokens with send and the web app.

Parameters

Name	Type	Description
`inbox (path)` required	string	Inbox ID (`ibx_…`).

Request body (JSON)

Field	Type	Description
`ciphertext` required	string	The RFC 5322 message, encrypted with the data key.
`draftId` required	string	A new random ID per message; the ciphertext is bound to it. Pattern: `^draft_[A-Za-z0-9_-]{16,64}$`.
`epoch` required	integer	The epoch from `/compose` the message was sealed to.
`from` required	string	A bare address the inbox may send as; it must match the message's From header.
`to` required	string[]	Every recipient (To, Cc and Bcc), as bare addresses.
`wrappedDek` required	string

Response body (JSON)

Field	Type	Description
`sent` required	true

Responses

Status	Body	Meaning
200	JSON	Accepted for delivery.
400	Error	The request is malformed.
401	Error	No token, or it expired: sign in again.
403	Error	The inbox can't send as `from`.
404	Error	Not found, or not yours.
422	Error	Refused: a sending limit or policy, with the reason.
503	Error	Temporary failure; try again later.

Events

List event types

GET/event-types

The event catalog: every event type K8 HQ records, with its JSON Schema. Audit-only types are listed with their visibility; they can't trigger rules. API tokens also get their project's own types (ext.*).

For API tokens and the web app.

Response body (JSON)

Field	Type	Description
`eventTypes` required	EventType[]

Responses

Status	Body	Meaning
200	JSON	The catalog.
401	Error	No token, or it expired: sign in again.

Register an event type

POST/event-types

Registers one of the project's own event types, ext.<thing>.<past-tense verb>, or updates it compatibly: within a version, data fields may only be added, and only as optional. Anything else needs a new version.

For API tokens with events:write.

Request body (JSON)

Field	Type	Description
`description` required	string
`name` required	string	Pattern: `^ext\.[a-z][a-z0-9_]\.[a-z][a-z0-9_]$`.
`data`	object[]
`version`	integer

{"data":[{"description":"The shop's order ID.","name":"orderId","required":true,"type":"string"}],"description":"An order left the warehouse.","name":"ext.order.shipped"}

Response body (JSON)

Field	Type	Description
`class` required	string
`data` required	object[]	The data fields.
`dataSchema` required	object	JSON Schema for the event's data.
`description` required	string
`name` required	string
`source` required	string
`status` required	experimental \| stable \| deprecated
`version` required	integer
`visibility` required	string
`subject`	string	What the event's subject holds.

Responses

Status	Body	Meaning
201	EventType	The registered type.
401	Error	No token, or it expired: sign in again.
403	Error	The token lacks events:write.
422	Error	Invalid, or an incompatible change within a version.

Read the project's events

GET/events

Every event of the project, oldest first, across its inboxes and the project itself: a page after a cursor, or with Accept: text/event-stream a live stream that resumes from Last-Event-ID. Each event's id: line in the stream is its cursor. You see inbox events for inboxes you may use; project-level events (access, domains, sending) need project:read; audit-only events (who read what) need audit:read and audit=true. Paged reads return events a few seconds old, so none arrive later behind the cursor; live streams send at once and may repeat an event after reconnecting, so dedupe by event id. The web app must name its inboxes and sees read state without who read it.

For API tokens with events:read and the web app.

Parameters

Name	Type	Description
`after (query)`	string	Cursor: return events after it (the `cursor` of the previous page, or an event's stream `id`).
`types (query)`	string	Comma-separated types or prefixes ending in `.`, e.g. `message.,ext.order.shipped`.
`inboxes (query)`	string	Comma-separated inbox IDs: only their events (and no project-level ones).
`audit (query)`	boolean	`true` includes audit-only events (needs audit:read).
`limit (query)`	integer	Page size, up to 500.
`Last-Event-ID (header)`	string	Live streams: resume after this cursor.

Response body (JSON)

Field	Type	Description
`cursor` required	string	Pass as after= for the next page.
`events` required	Event[]

Responses

Status	Body	Meaning
200	JSON, text/event-stream	A page, or the live stream.
400	Error	The web app must name inboxes.
401	Error	No token, or it expired: sign in again.
403	Error	Missing scope (events:read, or audit:read for audit=true).
404	Error	Not found, or not yours.

Publish an event

POST/events

Publishes one event of a type the project registered. Events are plaintext and kept until the project is deleted, so keep them thin: IDs and small facts, never message content or secrets (data up to 4 KB). Send Idempotency-Key to make retries safe: the same key within 24 hours returns the first event.

For API tokens with events:write.

Parameters

Name	Type	Description
`Idempotency-Key (header)`	string	Up to 255 characters; the same key returns the first event.

Request body (JSON)

Field	Type	Description
`type` required	string	A registered ext.* type.
`data`	object	Fields as the type defines them; up to 4 KB.
`inbox`	string	An inbox it concerns (ibx_…), if any.
`subject`	string	What the event is about, in your terms (e.g. an order number).

{"data":{"orderId":"1001"},"subject":"order 1001","type":"ext.order.shipped"}

Response body (JSON)

Field	Type	Description
`duplicate`	true
`id`	string

Responses

Status	Body	Meaning
200	JSON	A retry with the same Idempotency-Key: the first event.
201	JSON	Published.
401	Error	No token, or it expired: sign in again.
403	Error	The token lacks events:write.
404	Error	Not found, or not yours.
413	Error	data is over 4 KB.
422	Error	Unregistered type, or data that doesn't match it.

Stream inbox changes

GET/inboxes/{inbox}/events

Server-Sent Events announcing changes to the inbox, so a client can update its lists without polling. Each event carries IDs only; fetch details through the API. Event names are message.added, message.removed and message.flags, and each event's data is a LiveChange JSON object. The server sends a comment every 15 seconds to keep the connection open and ends the stream after 10 minutes, so reconnect with a fresh token.

For API tokens with messages:read and the web app.

Parameters

Name	Type	Description
`inbox (path)` required	string	Inbox ID (`ibx_…`).

Responses

Status	Body	Meaning
200	text/event-stream	An event stream.
401	Error	No token, or it expired: sign in again.
403	Error	The token lacks the scope, or (decrypted content) the inbox is zero-access, or the caller is a web session.
404	Error	Not found, or not yours.

Schemas

Attachment

Field	Type	Description
`contentType` required	string
`index` required	integer
`inline` required	boolean
`size` required	integer	Bytes, decoded.
`contentId`	string	For inline parts referenced from the HTML (`cid:`).
`filename`	string

Error

Field	Type	Description
`error` required	string

Event

A CloudEvents 1.0 event with K8 HQ's attributes.

Field	Type	Description
`actor` required	string	Who acted: a member (mem_), a token (tok_) or K8 HQ (sys_…). Empty when removed for privacy.
`class` required	string
`id` required	string
`scope` required	string	The project (prj_).
`sequence` required	string	Its position in its own stream (the inbox, or the project).
`source` required	string
`time` required	string
`type` required	string
`visibility` required	string
`causationid`	string
`containerid`	string	The inbox it concerns, if any.
`correlationid`	string
`data`	object
`dataschema`	string
`subject`	string

EventType

Field	Type	Description
`class` required	string
`data` required	object[]	The data fields.
`dataSchema` required	object	JSON Schema for the event's data.
`description` required	string
`name` required	string
`source` required	string
`status` required	experimental \| stable \| deprecated
`version` required	integer
`visibility` required	string
`subject`	string	What the event's subject holds.

Flag

A message flag, by its neutral name: the same vocabulary as events, whatever the channel. Mail apps' IMAP flags map onto it (\Seen is seen, $Junk is junk). Values: seen, answered, flagged, draft, forwarded, junk, not_junk.

InboxGrant

Field	Type	Description
`inboxId` required	string
`role` required	string	Your role in the inbox, e.g. owner.
`label`	string	Display name, usually the inbox's main address.

Label

Field	Type	Description
`id` required	string
`name` required	string
`total` required	integer
`unread` required	integer
`specialUse`	\Sent \| \Drafts \| \Trash \| \Junk \| \Archive	The label's role, as IMAP names it.

LiveChange

Field	Type	Description
`msgId` required	string
`type` required	message.added \| message.removed \| message.flags
`flags`	Flag[]	The message's flags now (message.flags).
`labelId`	string	The label a message was added to or removed from.
`uid`	integer	The message's number in the label (message.added).

MessageSummary

Field	Type	Description
`flags` required	Flag[]	The message's flags, by neutral name (the same names events use).
`id` required	string
`receivedAt` required	string
`size` required	integer	Bytes.
`uid` required	integer	The message's number in this label (0 when fetched outside a label).
`date`	string	The Date header.
`direction`	in \| out
`from`	string
`keywords`	string[]	Custom keywords mail apps have set, e.g. `$label1`.
`subject`	string
`to`	string

NewEventType

Field	Type	Description
`description` required	string
`name` required	string	Pattern: `^ext\.[a-z][a-z0-9_]\.[a-z][a-z0-9_]$`.
`data`	object[]
`version`	integer

WebFlag

The flags the API can change. Values: seen, flagged, answered.