# Gateway Advisory AI API (Web I)

**Status:** Interim contract shipped by Web I to unblock SDK/UI work. Align to the authoritative Advisory AI OpenAPI when the gateway routing plugin publishes it.

## Overview
- Gateway routes advisory AI traffic under `/advisory/ai/*`.
- Web clients must send tenant + trace headers and should avoid sending raw prompts in telemetry; use prompt hashes instead.

## Headers
- `X-StellaOps-Tenant` (required)
- `X-Stella-Project` (optional)
- `X-Stella-Trace-Id` (required)
- `X-Stella-Request-Id` (required; defaults to trace ID)
- `X-StellaOps-AI-Profile` (optional; e.g. `standard`)
- `X-StellaOps-Prompt-Hash` (recommended; send a stable hash, not the prompt)

## Scopes
- Read: `advisory-ai:read`
- Write/operate: `advisory-ai:write`

## Endpoints

### `POST /advisory/ai/jobs`
Creates a new advisory AI job.

- Request: `docs/api/gateway/samples/advisory-ai-start-job.json`
- Response: `docs/api/gateway/samples/advisory-ai-start-job-response.json`

### `GET /advisory/ai/jobs/{jobId}`
Returns job status and optional results once completed.

### `POST /advisory/ai/jobs/{jobId}/cancel`
Cancels a queued/running job.

### `GET /advisory/ai/jobs/{jobId}/events`
Server-sent events stream (JSON payload per message):

- Sample NDJSON: `docs/api/gateway/samples/advisory-ai-job-events.ndjson`