> ## 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.

# Gateway

> Submit events into the gateway and deliver them to participants - the routing contract for multi-participant messaging, including participants reachable at another 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](/concepts/sessions-and-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.

<ParamField body="sender_id" type="string" required>
  The sending participant's id.
</ParamField>

<ParamField body="sender_type" type="string" required>
  `human` or `ai`.
</ParamField>

<ParamField body="event_type" type="string" required>
  The event kind, e.g. `message`.
</ParamField>

<ParamField body="message" type="string">
  The message text.
</ParamField>

<ParamField body="session_id" type="string">
  The target session.
</ParamField>

<ParamField body="sender_gateway_url" type="string">
  Where replies should be delivered when the sender is reachable at another
  gateway URL.
</ParamField>

<ParamField body="metadata" type="object">
  Optional key/values (up to 50 keys).
</ParamField>

```bash theme={null}
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.

<ParamField body="recipient_id" type="string" required>
  The participant to deliver to.
</ParamField>

<ParamField body="event" type="object" required>
  The nested gateway event (same fields as submit).
</ParamField>

<ParamField body="session_id" type="string">
  The target session.
</ParamField>

<ParamField body="recipient_gateway_url" type="string">
  The recipient's gateway URL, when the recipient is reachable at another
  gateway.
</ParamField>

```bash theme={null}
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.                        |