> **Client contract note:** Apply [`shared/response-envelope.md`](../shared/response-envelope.md) to JSON responses after the response-contract release. Legacy wrapper examples below may reflect the prior API; the documented endpoint-specific payload fields are still useful. Not staging-verified.

# Verification, Realtime, Push and Core — verified contracts

Sources: `modules/{Verification,Realtime,Push,Core,FeatureFlags}/Routes/api.php` and matching controllers/requests on `main`; Core `ApiResponse.php`.

## POST /verification/request — public, throttle:auth

| Body field | Type | Required | Rules |
|---|---|---|---|
| `channel` | string | Yes | Must be configured in `verification.channels` or `verification.extra_channels`; exact enabled list depends on environment |
| `target` | string | Yes | max 190; when channel=`sms`, E.164 regex `^\+[1-9]\d{6,14}$` |
| `purpose` | string | Yes | max 60; lowercase letters, numbers, `_`, `.`, `-` |

**Request (illustrative valid shape if SMS enabled):**
```json
{"channel":"sms","target":"+201000000000","purpose":"registration"}
```
**200 response (exact literal from controller):**
```json
{"data":{"message":"If the target is valid, a code was sent."}}
```
This deliberately does not reveal whether the target exists.

## POST /verification/verify — public, throttle:auth

| Body field | Type | Required | Rules |
|---|---|---|---|
| `target` | string | Yes | max 190 |
| `purpose` | string | Yes | max 60; `[a-z0-9_.-]+` |
| `code` | string | Yes | 4–10 digits |

**Request:**
```json
{"target":"+201000000000","purpose":"registration","code":"123456"}
```
**200 response (illustrative proof):**
```json
{"data":{"verified":true,"proof":"<signed-verification-proof>"}}
```
Invalid/expired code throws business error with code `invalid_code`; exact HTTP error envelope/status requires separate exception-handler verification.

## POST /realtime/auth — authenticated, throttle 60/min

| Body field | Type | Required | Validation |
|---|---|---|---|
| `channel_name` | string | Yes | max 120 |
| `socket_id` | string | Yes | max 64 |

**Request:**
```json
{"channel_name":"private-example","socket_id":"1234.5678"}
```
Success: broadcaster-generated Pusher-compatible auth payload; exact shape depends on configured broadcaster. **403 response exact structure** (request_id is runtime-specific):
```json
{"error":{"code":"channel_forbidden","message":"You may not subscribe to this channel.","request_id":null}}
```
**501** when broadcaster is `null`/`log`:
```json
{"error":{"code":"realtime_not_configured","message":"No socket server is configured (BROADCAST_CONNECTION).","request_id":null}}
```

## POST /push/test — authenticated, throttle 5/min

No request body used. Queues a test push for the caller's registered devices.
**202 response:**
```json
{"data":{"queued":true}}
```
`queued=true` is not proof of delivery to the device.

## GET /health/live — public

**200 response:** `{"status":"ok"}` (no `data` wrapper).

## GET /health/ready — public

**200 when ready:** `{"status":"ok","checks":{"database":"ok","cache":"ok"}}`

**503 example when degraded:** `{"status":"degraded","checks":{"database":"fail","cache":"ok"}}`

## GET /locales — public

**200 response (illustrative locale values, verified structure):**
```json
{"data":[{"code":"ar","native_name":"<localized native name>","dir":"rtl","default":true}]}
```
`data[]`: `code` string, `native_name` string, `dir` (`rtl`/`ltr`), `default` boolean. Enabled locales and default are dynamic.

## GET /features — authenticated

**200 response (illustrative keys):**
```json
{"data":{"example_feature":true}}
```
`data` is a dynamic object mapping each defined feature name to a boolean resolved for the authenticated actor. Do not hardcode feature keys.
