git.stella-ops.org/docs/api/gateway/advisory-ai.md

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-Stella-Tenant (required; see docs/api/gateway/tenant-auth.md)
• 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