Advisory AI Gateway Contract

This contract describes how the Stella Ops Web gateway proxies Advisory AI traffic under /advisory/ai/*. It is the integration surface for SDK and Console clients that submit advisory analysis jobs and stream their results.

Status: Interim contract published to unblock SDK and UI work. Align to the authoritative Advisory AI OpenAPI once the gateway routing plugin publishes it.

Overview

• The gateway routes Advisory AI traffic under /advisory/ai/*.
• Clients must send tenant and trace headers on every request.
• Never place raw prompts in telemetry. Send a stable prompt hash instead (X-StellaOps-Prompt-Hash).

Security / headers

• X-StellaOps-TenantId (required; see tenant-auth).
• X-StellaOps-Project (optional; legacy alias X-Stella-Project is accepted only when the gateway is started with EnableLegacyHeaders=true).
• X-StellaOps-TraceId (required).
• X-StellaOps-RequestId (required; defaults to the 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:view
• Write / operate: advisory-ai:operate

Endpoints

POST /advisory/ai/jobs

Create a new Advisory AI job.

• Request sample: samples/advisory-ai-start-job.json
• Response sample: samples/advisory-ai-start-job-response.json

GET /advisory/ai/jobs/{jobId}

Return job status, and the results once the job has completed.

POST /advisory/ai/jobs/{jobId}/cancel

Cancel a queued or running job.

GET /advisory/ai/jobs/{jobId}/events

Stream job progress as Server-Sent Events (one JSON payload per message).

• Sample stream: samples/advisory-ai-job-events.ndjson