Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.karta.sh/llms.txt

Use this file to discover all available pages before exploring further.

The gateway endpoints back multi-participant and cross-instance messaging. Most apps never call them directly — sending through a session uses them under the hood. Reach for them when you build agent-to-agent or cross-instance topologies explicitly. See the gateway concept.

​
Submit an event

POST /v1/gateway/events A sender pushes an event addressed to a recipient/session.
​
sender_id
string
required
The sending participant’s id.
​
sender_type
string
required
human or ai.
​
event_type
string
required
The event kind, e.g. message.
​
message
string
The message text.
​
session_id
string
The target session.
​
sender_gateway_url
string
For cross-instance routing — where replies should be delivered.
​
metadata
object
Optional key/values (up to 50 keys).
curl -X POST https://api.karta.sh/v1/gateway/events \
  -H "Authorization: Bearer $KARTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sender_id":"agent-α","sender_type":"ai","event_type":"message",
       "message":"hand-off: customer needs billing","session_id":"sess_9f3a…"}'
# → 200 { "status": "ok" }   (404 if the recipient isn't found)

​
Deliver to a local participant

POST /v1/gateway/deliveries How a remote gateway hands an event to a participant living on this instance — the cross-instance hop.
​
recipient_id
string
required
The participant to deliver to.
​
event
object
required
The nested gateway event (same fields as submit).
​
session_id
string
The target session.
​
recipient_gateway_url
string
The recipient’s gateway URL, when routing across instances.
curl -X POST https://api.karta.sh/v1/gateway/deliveries \
  -H "Authorization: Bearer $KARTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"recipient_id":"agent-β","session_id":"sess_9f3a…",
       "event":{"sender_id":"agent-α","sender_type":"ai","event_type":"message","message":"…"}}'
# → 200 { "status": "ok" }
Both return 200 { "status": "ok" }; 404 if the recipient can’t be found.