Gateway

The gateway endpoints deliver events to participants, including participants reachable at another gateway URL. Most apps never call them directly - sending through a session uses them under the hood. Reach for them when you build agent-to-agent topologies explicitly. See Sessions & participants for the multi-participant model. Both endpoints require an API key. They exist only on runtimes with gateway support enabled.

Endpoint	Direction	Use when
`POST /v1/gateway/events`	Participant -> session	A participant submits an event into a session.
`POST /v1/gateway/deliveries`	Gateway -> participant	Another gateway delivers an event to a participant reachable here.

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

Where replies should be delivered when the sender is reachable at another gateway URL.

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-alpha","sender_type":"ai","event_type":"message",
       "message":"hand-off: customer needs billing","session_id":"sess_9f3a..."}'
# -> 200 { "status": "ok" }   (404 if the recipient is not found)

Deliver to a participant

POST /v1/gateway/deliveries How another gateway hands an event to a participant reachable at this gateway URL.

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 the recipient is reachable at another gateway.

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-beta","session_id":"sess_9f3a...",
       "event":{"sender_id":"agent-alpha","sender_type":"ai","event_type":"message","message":"..."}}'
# -> 200 { "status": "ok" }

Both return 200 { "status": "ok" }; 404 if the recipient cannot be found.

Failure signals

Status	Meaning	Recovery
`401`	Missing or invalid API key.	Send a server-side `kt_live_...` key.
`404`	The target session or recipient is not known to this gateway.	Check `session_id`, participant ids, and the remote gateway URL.
`422`	The request body does not match the schema.	Validate required fields before retrying.

Overview

Sessions

Consumer adapters

Submit an event

Deliver to a participant

Failure signals

​Submit an event

​Deliver to a participant

​Failure signals

Submit an event

Deliver to a participant

Failure signals