Skip to content
Olivares AI docs

Publishes one governed direct Message and required Delivery.

POST
/v1/m/sessions/messages/send
 
curl --request POST \
  --url https://example.com/v1/m/sessions/messages/send \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 2489E9AD-2EE2-8E00-8EC9-32D5F69181C0' \
  --data '{ "available_at": "2026-04-15T12:00:00Z", "channel_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "content": { "blocks": [ { "code": "example", "format": "", "reference": { "hash": "example", "kind": "example", "ref": "example" }, "text": "example", "type": "text" } ], "subject": "example" }, "recipient": { "kind": "user", "ref": "example" }, "urgency": "" }'

Publishes one governed direct Message and required Delivery.

Authorizations

Section titled “ Authorizations ”

Parameters

Section titled “ Parameters ”

Header Parameters

Section titled “ Header Parameters ”
X-Olivares-Tenant
string format: uuid

Target tenant id; required when the principal can act in more than one tenant.

Idempotency-Key
required
string format: uuid

Canonical UUID binding exact send retries.

If-Plan-Hash
string
/^[0-9a-f]{64}$/

Optional SHA-256 plan precondition; when supplied, publication must reproduce it.

Request Body required

Section titled “ Request Body required ”
Media type application/json
object
available_at
string format: date-time
channel_id
required
string format: uuid
content
required
object
blocks
required
Array<object>
>= 1 items <= 64 items
object
code
string
format
string
Allowed values: "" plain markdown
reference
Any of:
object
hash
string
kind
required
string
>= 1 characters
ref
required
string
>= 1 characters
text
string
type
required
string
Allowed values: text reference status action_ref
subject
required
string
recipient
required
object
kind
required
string
Allowed values: user agent session
ref
required
string
>= 1 characters <= 1024 characters
urgency
string
Allowed values: "" normal high critical

Responses

Section titled “ Responses ”

200

Section titled “ 200 ”

Exact durable send receipt replay

Media type application/json
object
ack_quorum
required
integer format: int64
audience_hash
required
string
audit_seq
required
integer format: int64
channel_id
required
string format: uuid
code
required
string
command_id
required
string format: uuid
delivery_count
required
integer format: int64
delivery_id
required
string format: uuid
event_id
required
string format: uuid
fulfillment
required
object
acknowledged
required
integer format: int64
quorum
integer format: int64
required
required
integer format: int64
state
required
string
unmet
required
integer format: int64
viable
required
integer format: int64
message_id
required
string format: uuid
payload_digest
required
string
plan_hash
required
string
replayed
required
boolean
required_count
required
integer format: int64
state
required
string
verdict
required
string
version
required
integer format: int64
Example generated 
{
  "ack_quorum": 1,
  "audience_hash": "example",
  "audit_seq": 1,
  "channel_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "code": "example",
  "command_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "delivery_count": 1,
  "delivery_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "event_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "fulfillment": {
    "acknowledged": 1,
    "quorum": 1,
    "required": 1,
    "state": "example",
    "unmet": 1,
    "viable": 1
  },
  "message_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "payload_digest": "example",
  "plan_hash": "example",
  "replayed": true,
  "required_count": 1,
  "state": "example",
  "verdict": "example",
  "version": 1
}

201

Section titled “ 201 ”

Message and Delivery created

Media type application/json
object
ack_quorum
required
integer format: int64
audience_hash
required
string
audit_seq
required
integer format: int64
channel_id
required
string format: uuid
code
required
string
command_id
required
string format: uuid
delivery_count
required
integer format: int64
delivery_id
required
string format: uuid
event_id
required
string format: uuid
fulfillment
required
object
acknowledged
required
integer format: int64
quorum
integer format: int64
required
required
integer format: int64
state
required
string
unmet
required
integer format: int64
viable
required
integer format: int64
message_id
required
string format: uuid
payload_digest
required
string
plan_hash
required
string
replayed
required
boolean
required_count
required
integer format: int64
state
required
string
verdict
required
string
version
required
integer format: int64
Example generated 
{
  "ack_quorum": 1,
  "audience_hash": "example",
  "audit_seq": 1,
  "channel_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "code": "example",
  "command_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "delivery_count": 1,
  "delivery_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "event_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "fulfillment": {
    "acknowledged": 1,
    "quorum": 1,
    "required": 1,
    "state": "example",
    "unmet": 1,
    "viable": 1
  },
  "message_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "payload_digest": "example",
  "plan_hash": "example",
  "replayed": true,
  "required_count": 1,
  "state": "example",
  "verdict": "example",
  "version": 1
}

400

Section titled “ 400 ”

Bad request

Media type application/json
object
Example generated 
{}

401

Section titled “ 401 ”

Unauthenticated

Media type application/json
object
Example generated 
{}

403

Section titled “ 403 ”

Forbidden

Media type application/json
object
Example generated 
{}

404

Section titled “ 404 ”

Not found

Media type application/json
object
Example generated 
{}

409

Section titled “ 409 ”

Conflict

Media type application/json
object
Example generated 
{}

412

Section titled “ 412 ”

Precondition failed

Media type application/json
object
Example generated 
{}

429

Section titled “ 429 ”

Rate limited

Media type application/json
object
Example generated 
{}

503

Section titled “ 503 ”

Current authority, custody or store evidence is unavailable; or, with code commit_outcome_unknown, the write was issued and its outcome was never learned, so it may be durable and must not be retried automatically

Media type application/json
object
Example generated 
{}