Drafts
An agent proposes, a human approves. Nothing leaves unapproved.
Every endpoint needs Authorization: Bearer lk_live_.... See
Conventions for headers, status codes
and error shape.
List drafts
GET /v1/drafts · scope inboxes:read
Filter with ?status=pending_approval|sent|rejected|cancelled. Keys see drafts of granted mailboxes; admin sessions see all.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
status |
query | string | |
limit |
query | integer |
Response 200
Drafts
| Field | Type | Notes |
|---|---|---|
drafts |
array of Draft | Required. |
Get a draft
GET /v1/drafts/{draftID} · scope inboxes:read
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
draftID |
path | string | Required. |
Response 200
Draft
| Field | Type | Notes |
|---|---|---|
id |
string | Required. |
mailbox_id |
string | Required. |
mailbox |
string | |
thread_id |
string | |
to |
array of string | Required. |
cc |
array of string | |
subject |
string | |
body_text |
string | |
status |
string (pending_approval, sent, rejected, cancelled) |
Required. |
policy_flags |
PolicyFlags | Required. Why a draft was held. A key is absent when that check passed. The set is closed: a flag added to the policy engine must be added here too, or typed clients will drop it. |
reviewed_at |
string | |
sent_message_id |
string | |
created_at |
string | Required. |
updated_at |
string | Required. |
Approve a pending draft (human)
POST /v1/drafts/{draftID}/approve · scope tenant:admin
Sends the draft exactly as reviewed, through the agent stream (loop detector included). Fires draft.approved.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
draftID |
path | string | Required. |
Response 200
Sent
| Field | Type | Notes |
|---|---|---|
draft_id |
string | Required. |
status |
string (pending_approval, sent) |
Required. |
policy_flags |
PolicyFlags | Required. Why a draft was held. A key is absent when that check passed. The set is closed: a flag added to the policy engine must be added here too, or typed clients will drop it. |
thread_id |
string | |
sent |
AgentSendResult |
Withdraw a pending draft
POST /v1/drafts/{draftID}/cancel · scope inboxes:write
Only the API key that created the draft may cancel it.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
draftID |
path | string | Required. |
Response 200
Cancelled
| Field | Type | Notes |
|---|---|---|
id |
string | Required. |
mailbox_id |
string | Required. |
mailbox |
string | |
thread_id |
string | |
to |
array of string | Required. |
cc |
array of string | |
subject |
string | |
body_text |
string | |
status |
string (pending_approval, sent, rejected, cancelled) |
Required. |
policy_flags |
PolicyFlags | Required. Why a draft was held. A key is absent when that check passed. The set is closed: a flag added to the policy engine must be added here too, or typed clients will drop it. |
reviewed_at |
string | |
sent_message_id |
string | |
created_at |
string | Required. |
updated_at |
string | Required. |
Reject a pending draft (human)
POST /v1/drafts/{draftID}/reject · scope tenant:admin
Body: {“reason”: “…”} (optional). Fires draft.rejected.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
draftID |
path | string | Required. |
Response 200
Rejected
| Field | Type | Notes |
|---|---|---|
id |
string | Required. |
mailbox_id |
string | Required. |
mailbox |
string | |
thread_id |
string | |
to |
array of string | Required. |
cc |
array of string | |
subject |
string | |
body_text |
string | |
status |
string (pending_approval, sent, rejected, cancelled) |
Required. |
policy_flags |
PolicyFlags | Required. Why a draft was held. A key is absent when that check passed. The set is closed: a flag added to the policy engine must be added here too, or typed clients will drop it. |
reviewed_at |
string | |
sent_message_id |
string | |
created_at |
string | Required. |
updated_at |
string | Required. |
Propose a new conversation as a draft
POST /v1/inboxes/{mailbox}/drafts · scope inboxes:draft
New-conversation drafts ALWAYS require human approval (policy flag new_thread). Idempotency-Key required.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
mailbox |
path | string | Required. |
Idempotency-Key |
header | string | Required. |
Response 202
Draft outcome (pending_approval)
| Field | Type | Notes |
|---|---|---|
draft_id |
string | Required. |
status |
string (pending_approval, sent) |
Required. |
policy_flags |
PolicyFlags | Required. Why a draft was held. A key is absent when that check passed. The set is closed: a flag added to the policy engine must be added here too, or typed clients will drop it. |
thread_id |
string | |
sent |
AgentSendResult |
Propose a reply as a draft
POST /v1/threads/{threadID}/drafts · scope inboxes:draft
The safe default over /reply: the deterministic policy engine auto-sends clean in-thread replies and holds anything risky (PII, new recipients, injection-flagged threads, always-approve mailboxes) for human approval. A key with inboxes:draft but not inboxes:write may only propose: its clean drafts are held too, never auto-sent. Fires draft.pending_approval when held. Idempotency-Key required.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
threadID |
path | string | Required. |
Idempotency-Key |
header | string | Required. |
Response 202
Outcome (sent | pending_approval) with policy_flags
| Field | Type | Notes |
|---|---|---|
draft_id |
string | Required. |
status |
string (pending_approval, sent) |
Required. |
policy_flags |
PolicyFlags | Required. Why a draft was held. A key is absent when that check passed. The set is closed: a flag added to the policy engine must be added here too, or typed clients will drop it. |
thread_id |
string | |
sent |
AgentSendResult |