Recipients

Humans an org can reach, with consent.

Generated from the contract, version 2.0.0-draft.2 (OpenAPI). Base URL https://usekabu.com/api. Errors are problem details, each code with its own page.

List recipients

GET/v2/recipients

Auth: an API key, or a signed-in human’s token (the Kabu apps).
Scopes: recipients:write.
Signed-in humans: admin.

Parameter	In	Type	Required	Description
`limit`	query	integer, from 1 to 100	Optional
`after`	query	string	Optional	Opaque cursor from next_cursor.
`Kabu-Org`	header	string	Optional	Select a live membership (default personal org); non-member is 404. Human tokens are live-only. Caller user id is distinct from billing owner.

Status	Means	Body
`200`	OK	RecipientList
`4XX`	Error	Problem
`5XX`	Error	Problem

curl "https://usekabu.com/api/v2/recipients" \
  -H "Authorization: Bearer $KABU_API_KEY"

Get a recipient

GET/v2/recipients/{recipient}

Auth: an API key, or a signed-in human’s token (the Kabu apps).
Scopes: recipients:write.
Signed-in humans: admin.

Parameter	In	Type	Required	Description
`recipient`	path	string	Required	An id or slug.
`Kabu-Org`	header	string	Optional	Select a live membership (default personal org); non-member is 404. Human tokens are live-only. Caller user id is distinct from billing owner.

Status	Means	Body
`200`	OK	Recipient
`4XX`	Error	Problem
`5XX`	Error	Problem

curl "https://usekabu.com/api/v2/recipients/$RECIPIENT" \
  -H "Authorization: Bearer $KABU_API_KEY"

Create or update a recipient

PUT/v2/recipients/{recipient}

Auth: an API key, or a signed-in human’s token (the Kabu apps).
Scopes: recipients:write.
Signed-in humans: admin.

Parameter	In	Type	Required	Description
`recipient`	path	string	Required	An id or slug.
`Kabu-Org`	header	string	Optional	Select a live membership (default personal org); non-member is 404. Human tokens are live-only. Caller user id is distinct from billing owner.

Request body: RecipientWrite.

Status	Means	Body
`200`	OK	Recipient
`4XX`	Error	Problem
`5XX`	Error	Problem

curl -X PUT "https://usekabu.com/api/v2/recipients/$RECIPIENT" \
  -H "Authorization: Bearer $KABU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Delete a recipient

DELETE/v2/recipients/{recipient}

Auth: an API key, or a signed-in human’s token (the Kabu apps).
Scopes: recipients:write.
Signed-in humans: admin.

Parameter	In	Type	Required	Description
`recipient`	path	string	Required	An id or slug.
`Kabu-Org`	header	string	Optional	Select a live membership (default personal org); non-member is 404. Human tokens are live-only. Caller user id is distinct from billing owner.

Status	Means	Body
`204`	Done
`4XX`	Error	Problem
`5XX`	Error	Problem

curl -X DELETE "https://usekabu.com/api/v2/recipients/$RECIPIENT" \
  -H "Authorization: Bearer $KABU_API_KEY"

Create a consented pairing link (app, Web Push or web)

POST/v2/recipients/{recipient}/invite

A pairing link is a human-voice capability: a key holding messages:write gets 403 self_response_forbidden, so an agent can never pair itself as a recipient. Use a service key or a user token.

Auth: an API key, or a signed-in human’s token (the Kabu apps).
Scopes: recipients:write.
Refused to: a key holding messages:write.
Signed-in humans: admin.

Parameter	In	Type	Required	Description
`recipient`	path	string	Required	`rcp_…` or `ext:…`.
`Idempotency-Key`	header	string, at most 255 characters	Optional	Retry-safe key. For messages, sessions and responses it binds to the created object for its life; elsewhere for 24 h.
`Kabu-Org`	header	string	Optional	Select a live membership (default personal org); non-member is 404. Human tokens are live-only. Caller user id is distinct from billing owner.

Status	Means	Body
`201`	OK	Invite
`429`	A rate, concurrency or quota limit was reached	Problem
`4XX`	Error	Problem
`5XX`	Error	Problem

curl -X POST "https://usekabu.com/api/v2/recipients/$RECIPIENT/invite" \
  -H "Authorization: Bearer $KABU_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Preview recipient pairing consent

GET/v2/recipient_pairings/preview

Public capability preview for recipients.invite only; org invitation tokens are refused. No membership is created.

Auth: no credentials.

Parameter	In	Type	Required	Description
`token`	query	string	Required

Status	Means	Body
`200`	OK	RecipientPairingPreview
`429`	A rate, concurrency or quota limit was reached	Problem
`4XX`	Error	Problem
`5XX`	Error	Problem

curl "https://usekabu.com/api/v2/recipient_pairings/preview?token=%E2%80%A6"

Recipients pairing accept

POST/v2/recipient_pairings/accept

User token and explicit consent only; consume the single-use, hashed, expiring recipient pairing token and bind its recipient to the authenticated person. No Kabu-Org or prior membership required; never creates membership. Org invitation tokens are refused. Return the consenting recipient view with settings/metadata projected to empty objects.

Kabu apps only: a signed-in human’s token. Integrations use API keys.
Signed-in humans: self.

Parameter	In	Type	Required	Description
`Idempotency-Key`	header	string, at most 255 characters	Optional	Retry-safe key. For messages, sessions and responses it binds to the created object for its life; elsewhere for 24 h.

Request body: RecipientPairingAccept.

Status	Means	Body
`200`	OK	Recipient
`429`	A rate, concurrency or quota limit was reached	Problem
`4XX`	Error	Problem
`5XX`	Error	Problem

curl -X POST "https://usekabu.com/api/v2/recipient_pairings/accept" \
  -H "Authorization: Bearer $KABU_USER_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"token":"…","consent":true}'

Schemas

RecipientList

Property	Type	Required
`object`	`"list"`	Required
`data`	array of Recipient	Required
`has_more`	boolean	Required
`next_cursor`	string or null	Required

Recipient

Property	Type	Required	Description
`object`	`"recipient"`	Required
`id`	string	Required
`external_id`	string or null	Required
`name`	string or null	Required
`email`	string or null	Required
`status`	string	Required	invited, active, unsubscribed or disabled (open).
`channels`	array of Channel	Required	Reachable now. Empty means links only.
`settings`	SettingsView	Required	Layered: org → project → agent → recipient. Unset fields inherit.
`metadata`	Metadata	Required	Your own key/value pairs (≤ 50 keys, values ≤ 500 chars), returned verbatim on every object and event.
`created_at`	Timestamp	Required

RecipientWrite

Property	Type	Required	Description
`external_id`	string, at most 120 characters	Optional
`name`	string, at most 80 characters	Optional
`email`	string (email)	Optional
`locale`	string	Optional
`time_zone`	string	Optional
`settings`	Settings	Optional	Layered: org → project → agent → recipient. Unset fields inherit.
`metadata`	Metadata	Optional	Your own key/value pairs (≤ 50 keys, values ≤ 500 chars), returned verbatim on every object and event.

Unknown properties are refused.

Invite

A consented pairing link to the Kabu app, Web Push or the web.

Property	Type	Required
`object`	`"invite"`	Required
`url`	string (uri)	Required
`expires_at`	Timestamp	Required

RecipientPairingPreview

Capability preview only, no membership or recipient settings/metadata. Distinct from org invites.

Property	Type	Required
`object`	`"recipient_pairing"`	Required
`recipient`	string	Required
`recipient_name`	string or null	Required
`org_name`	string	Required
`expires_at`	Timestamp	Required

RecipientPairingAccept

Bind only the authenticated consenting person to the token’s recipient. Explicit true consent required; no user/recipient/org/role may be supplied. Never creates membership or grants administration.

Property	Type	Required	Description
`token`	string, 1 to 256 characters	Required
`consent`	`true`	Required

Unknown properties are refused.