diff --git a/api-reference/index.mdx b/api-reference/index.mdx
index 446dd82..0b2bd6e 100644
--- a/api-reference/index.mdx
+++ b/api-reference/index.mdx
@@ -24,6 +24,9 @@ This section documents API interfaces only. It does not define protocol concepts
Application API for Impact Hub Registry service workflows.
+
+ Session endpoint for the IXO USSD gateway — accepts input from telecom gateways and returns USSD responses.
+
## Boundary between protocol and services
diff --git a/api-reference/ussd-api.mdx b/api-reference/ussd-api.mdx
new file mode 100644
index 0000000..33045d2
--- /dev/null
+++ b/api-reference/ussd-api.mdx
@@ -0,0 +1,201 @@
+---
+title: "USSD gateway API"
+icon: "tower-cell"
+description: "Endpoint reference for the IXO USSD gateway session API."
+---
+
+## Overview
+
+The IXO USSD gateway exposes a single session endpoint that telecom gateways call for each user interaction, plus debug and health endpoints for operators.
+
+All endpoints accept and return JSON unless otherwise noted. The main session endpoint returns plain text in the USSD response format.
+
+## Authentication
+
+The `/api/ussd` endpoint does not require authentication by default. It is intended to be called by your telecom gateway server, not directly from a browser. Restrict access at the network or reverse-proxy layer in production.
+
+## Base URL
+
+```text
+http://YOUR_SERVER:3000
+```
+
+The default port is `3000`. Set `PORT` in your environment to override.
+
+## Session endpoint
+
+### POST /api/ussd
+
+Processes a USSD interaction. Called by the telecom gateway once per user input during a session.
+
+**Request**
+
+```json
+{
+ "sessionId": "string",
+ "serviceCode": "string",
+ "phoneNumber": "string",
+ "text": "string"
+}
+```
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `sessionId` | string | yes | Unique session identifier assigned by the telecom gateway |
+| `serviceCode` | string | yes | USSD service code the user dialled, e.g. `*1234#` |
+| `phoneNumber` | string | yes | User's phone number in E.164 international format, e.g. `+260971234567` |
+| `text` | string | yes | User input accumulated during the session. Empty string on initial dial |
+
+**Validation rules**
+
+- `phoneNumber` must be E.164 format
+- `serviceCode` must match USSD format, e.g. `*1234#` or `*123*456#`
+- `text` maximum 182 characters (USSD protocol limit)
+- `sessionId` maximum 100 characters
+
+**Response**
+
+Plain text. The first word indicates whether the session continues or ends.
+
+```
+CON