Advisory Ai API Reference

Operations

GET /api/v1/buildinfo

API alias for /buildinfo.json (same payload).

Responses:

GET /api/v1/chat/doctor

Returns chat limit status and tool access diagnostics

Returns a diagnostics report for the current tenant and user, including remaining quota across all dimensions (requests/min, requests/day, tokens/day, tool calls/day), tool provider availability, and the last quota denial if any. Referenced by error responses via the doctor action hint.

Responses:

POST /api/v1/chat/evidence-preview

Previews the evidence bundle that would be assembled for a query

Assembles and returns a preview of the evidence bundle that would be passed to the LLM for the specified finding, without generating an AI response. Indicates which evidence types are available (VEX, reachability, binary patch, provenance, policy, ops memory, fix options) and their status.

Parameters:

Responses:

POST /api/v1/chat/intent

Detects intent from a user query without generating a full response

Classifies the user query into one of the advisory chat intents (explain, remediate, assess-risk, compare, etc.) and extracts structured parameters such as finding ID, package PURL, image reference, and environment. Useful for pre-routing or UI intent indicators without consuming LLM quota.

Responses:

POST /api/v1/chat/query

Processes a chat query and returns an evidence-grounded response

Analyzes the user query, assembles evidence bundle, and generates a response with citations.

Parameters:

Responses:

POST /api/v1/chat/query/stream

Streams a chat response as Server-Sent Events

Processes the query and streams the response tokens as SSE events.

Parameters:

Responses:

GET /api/v1/chat/settings

Gets effective chat settings for the caller

Returns the effective advisory chat settings for the current tenant and user, merging global defaults, tenant overrides, and user overrides. Includes quota limits and tool access configuration.

Responses:

PUT /api/v1/chat/settings

Updates chat settings overrides (tenant or user)

Applies quota and tool access overrides for the current tenant (default) or a specific user (scope=user). Overrides are layered on top of global defaults; only fields present in the request body are changed.

Parameters:

Responses:

DELETE /api/v1/chat/settings

Clears chat settings overrides (tenant or user)

Removes all tenant-level or user-level chat settings overrides, reverting the affected scope to global defaults. Use scope=user to clear only the user-level override for the current user.

Parameters:

Responses:

GET /api/v1/chat/status

Gets the status of the advisory chat service

Returns the current operational status of the advisory chat service, including whether chat is enabled, the configured inference provider and model, maximum token limit, and whether guardrails and audit logging are active.

Responses:

GET /buildinfo.json

Image build provenance (module, gitSha, gitCommitTime, imageBuiltAt, branch) for drift detection.

Responses:

GET /health

Responses:

GET /health/live

Responses:

GET /health/model

Responses:

GET /health/ready

Responses:

GET /v1/advisory-ai/adapters/llm/providers

Lists LLM providers exposed via the unified adapter layer.

Returns all LLM providers registered in the unified plugin catalog, including their configuration status, validation result, availability, and the completion path to use for each provider. Configured-but-invalid providers are included with error details. Use this endpoint to discover which providers are ready to serve completions before invoking them.

Responses:

POST /v1/advisory-ai/adapters/llm/{providerId}/chat/completions

OpenAI-compatible chat completion for a specific unified provider.

Submits a chat completion request to the specified LLM provider via the unified adapter layer using an OpenAI-compatible message format. Streaming is not supported; use non-streaming mode only. Returns 404 if the provider is not configured for adapter exposure, 503 if the provider is temporarily unavailable. Caller scopes are validated against gateway-managed headers.

Parameters:

Responses:

POST /v1/advisory-ai/adapters/openai/v1/chat/completions

OpenAI-compatible chat completion alias backed by providerId=openai.

Convenience alias that routes chat completion requests to the provider with id ‘openai’, using the same OpenAI-compatible request/response format as the generic provider endpoint. Intended for drop-in compatibility with clients expecting the standard OpenAI path. Streaming is not supported.

Responses:

GET /v1/advisory-ai/attestations/recent

List recent AI attestations for the current tenant

Returns the most recent AI run attestations for the authenticated tenant, ordered by creation time descending. Limit defaults to 20 and is capped at 100. Use this endpoint to monitor recent AI activity and surface attestations for downstream signing or audit workflows.

Parameters:

Responses:

POST /v1/advisory-ai/attestations/verify

Verify the cryptographic integrity of an AI run attestation

Verifies the content digest and DSSE envelope signature of a previously recorded AI run attestation. Returns a structured result including per-component validity flags (digest, signature) and the signing key ID. Returns 400 if the attestation is not found, is tampered, or belongs to a different tenant.

Responses:

POST /v1/advisory-ai/companion/explain

Responses:

GET /v1/advisory-ai/consent

Responses:

POST /v1/advisory-ai/consent

Responses:

DELETE /v1/advisory-ai/consent

Responses:

GET /v1/advisory-ai/conversations

Legacy conversation list endpoint (deprecated).

Lists conversations from the legacy conversation surface. Migrate listing flows to /api/v1/chat/* before the 2026-12-31 UTC sunset.

Parameters:

Responses:

POST /v1/advisory-ai/conversations

Legacy conversation-creation endpoint (deprecated).

Creates a chat conversation using the legacy conversation surface. This endpoint family is deprecated in favor of /api/v1/chat/* and is scheduled for sunset on 2026-12-31 UTC.

Responses:

GET /v1/advisory-ai/conversations/{conversationId}

Legacy conversation-read endpoint (deprecated).

Returns conversation state from the legacy conversation surface. Migrate readers to /api/v1/chat/* before the 2026-12-31 UTC sunset.

Parameters:

Responses:

DELETE /v1/advisory-ai/conversations/{conversationId}

Legacy conversation delete endpoint (deprecated).

Deletes a conversation on the legacy conversation surface. Migrate clients to /api/v1/chat/* before the 2026-12-31 UTC sunset.

Parameters:

Responses:

POST /v1/advisory-ai/conversations/{conversationId}/turns

Legacy conversation add-turn endpoint (deprecated).

Adds a conversational turn on the legacy conversation surface. Canonical payload field is content. Legacy message is accepted for compatibility only during the migration window ending 2026-12-31 UTC.

Parameters:

Responses:

POST /v1/advisory-ai/explain

Responses:

GET /v1/advisory-ai/explain/{explanationId}/replay

Parameters:

Responses:

POST /v1/advisory-ai/index/rebuild

Rebuilds AdvisoryAI knowledge search index from deterministic local sources.

Triggers a full rebuild of the knowledge search index from local deterministic sources: product documentation files, embedded OpenAPI specs, and Doctor health check metadata. The rebuild is synchronous and returns document, chunk, and operation counts with duration. Requires admin-level scope; does not fetch external content.

Responses:

POST /v1/advisory-ai/justify

Responses:

GET /v1/advisory-ai/outputs/{cacheKey}

Parameters:

Responses:

POST /v1/advisory-ai/pipeline/{taskType}

Parameters:

Responses:

POST /v1/advisory-ai/pipeline:batch

Responses:

POST /v1/advisory-ai/policy/studio/compile

Responses:

POST /v1/advisory-ai/policy/studio/generate

Responses:

POST /v1/advisory-ai/policy/studio/parse

Responses:

POST /v1/advisory-ai/policy/studio/validate

Responses:

GET /v1/advisory-ai/rate-limits

Responses:

POST /v1/advisory-ai/remediate

Responses:

POST /v1/advisory-ai/remediation/apply

Responses:

POST /v1/advisory-ai/remediation/plan

Responses:

GET /v1/advisory-ai/remediation/status/{prId}

Parameters:

Responses:

GET /v1/advisory-ai/runs

Queries runs with filters

Returns a paginated list of AI investigation runs for the current tenant, optionally filtered by initiator, CVE ID, component, and status. Supports skip/take pagination. Results are ordered by creation time descending.

Parameters:

Responses:

POST /v1/advisory-ai/runs

Creates a new AI investigation run

Creates a new AI investigation run scoped to the authenticated tenant, capturing the title, objective, and optional CVE/component/SBOM context. The run begins in the Created state and accumulates events as the investigation progresses. Returns 201 with the initial run state and a Location header.

Responses:

GET /v1/advisory-ai/runs/active

Gets active runs for the current user

Returns up to 50 AI investigation runs in Created, Active, or PendingApproval state that were initiated by the current user within the authenticated tenant. Use this endpoint to resume in-progress investigations or surface runs awaiting user input.

Responses:

GET /v1/advisory-ai/runs/pending-approval

Gets runs pending approval

Returns up to 50 AI investigation runs in the PendingApproval state for the authenticated tenant. Use this endpoint to surface runs that are blocked on a human approval decision before their proposed actions can be executed.

Responses:

GET /v1/advisory-ai/runs/{runId}

Gets a run by ID

Returns the current state of an AI investigation run, including status, event count, artifact count, content digest, attestation flag, context, and approval info. Returns 404 if the run does not exist or belongs to a different tenant.

Parameters:

Responses:

POST /v1/advisory-ai/runs/{runId}/actions

Proposes an action in the run

Records an AI-proposed action in a run, including the action type, subject, rationale, parameters, and whether human approval is required before execution. Actions flagged as requiring approval transition the run to PendingApproval once approval is requested. Returns 404 if the run is not active.

Parameters:

Responses:

POST /v1/advisory-ai/runs/{runId}/actions/{actionEventId}/execute

Executes an approved action

Marks a previously proposed and approved action as executed, recording the execution result in the run timeline. Only actions that have been approved may be executed; attempting to execute a pending or rejected action returns 400. Returns 404 if the run or action event does not exist.

Parameters:

Responses:

POST /v1/advisory-ai/runs/{runId}/approval/decide

Approves or rejects a run

Records an approval or rejection decision for a run in PendingApproval state. On approval, the run transitions back to Active so approved actions can be executed. On rejection, the run is cancelled. Returns 400 if the run is not in an approvable state.

Parameters:

Responses:

POST /v1/advisory-ai/runs/{runId}/approval/request

Requests approval for pending actions

Transitions a run to the PendingApproval state and notifies the designated approvers. The request body specifies the approver IDs and an optional reason. Returns the updated run state. Returns 404 if the run does not exist or is not in a state that allows approval requests.

Parameters:

Responses:

POST /v1/advisory-ai/runs/{runId}/artifacts

Adds an artifact to the run

Attaches an artifact (evidence pack, report, SBOM snippet, or other typed asset) to an active run. The artifact is recorded with its content digest, media type, size, and optional inline content. Adding an artifact updates the run’s content digest, contributing to its attestation chain.

Parameters:

Responses:

POST /v1/advisory-ai/runs/{runId}/attest

Creates an attestation for a completed run

Generates and persists a cryptographic attestation for a completed AI investigation run, recording the content digest, model metadata, and claim hashes. The attestation can optionally be signed via the attestation sign endpoint. Returns 400 if the run is not in a terminal state or has already been attested.

Parameters:

Responses:

GET /v1/advisory-ai/runs/{runId}/attestation

Get the attestation record for a completed AI run

Returns the AI attestation for a completed investigation run, including the DSSE envelope if the run was cryptographically signed. Tenant isolation is enforced; requests for runs belonging to a different tenant return 404. Returns 404 if the run has not been attested.

Parameters:

Responses:

POST /v1/advisory-ai/runs/{runId}/cancel

Cancels a run

Transitions an active or pending-approval AI investigation run to the Cancelled terminal state, optionally recording a cancellation reason. Cancelled runs are immutable and excluded from active and pending-approval queries. Returns 400 if the run is already in a terminal state.

Parameters:

Responses:

GET /v1/advisory-ai/runs/{runId}/claims

List AI-generated claims for a run

Returns all claim-level attestations recorded during an AI investigation run, each describing an individual assertion made by the AI (e.g. reachability verdict, remediation recommendation, risk rating). Claims are linked to the parent run attestation and can be independently verified.

Parameters:

Responses:

POST /v1/advisory-ai/runs/{runId}/complete

Completes a run

Transitions an active AI investigation run to the Completed terminal state, optionally recording a summary of findings. Once completed, the run is immutable and ready for attestation. Returns 400 if the run is already in a terminal state.

Parameters:

Responses:

POST /v1/advisory-ai/runs/{runId}/events

Adds an event to a run

Appends a typed event to an active AI investigation run, supporting arbitrary event types with optional content payload, evidence links, and parent event reference for threading. Returns 201 with the created event. Returns 404 if the run does not exist or is in a terminal state.

Parameters:

Responses:

POST /v1/advisory-ai/runs/{runId}/handoff

Hands off a run to another user

Transfers ownership of an active AI investigation run to another user within the same tenant. A hand-off event is recorded in the run timeline with the target user ID and an optional message. Returns 404 if the run does not exist or the target user is not valid.

Parameters:

Responses:

GET /v1/advisory-ai/runs/{runId}/timeline

Gets the event timeline for a run

Returns the ordered event timeline for an AI investigation run, including user turns, assistant turns, proposed actions, approvals, and artifact additions. Supports skip/take pagination over the event sequence. Returns 404 if the run does not exist.

Parameters:

Responses:

POST /v1/advisory-ai/runs/{runId}/turns/assistant

Adds an assistant turn to the run

Appends an AI assistant conversational turn to an active run, recording the generated message and optional evidence links. Assistant turns are included in the run content digest and contribute to the attestable evidence chain for the investigation.

Parameters:

Responses:

POST /v1/advisory-ai/runs/{runId}/turns/user

Adds a user turn to the run

Appends a user conversational turn to an active AI investigation run, recording the message text, actor ID, and optional evidence links. User turns drive the investigation dialogue and are included in the run content digest for attestation purposes.

Parameters:

Responses:

POST /v1/advisory-ai/search

Searches AdvisoryAI deterministic knowledge index (docs/api/doctor).

Performs a hybrid full-text and vector similarity search over the AdvisoryAI deterministic knowledge index, which is composed of product documentation, OpenAPI specs, and Doctor health check projections. Supports filtering by content type (docs, api, doctor), product, version, service, and tags. Returns ranked result snippets with actionable open-actions for UI navigation.

Responses:

POST /v1/advisory-ai/search/analytics

Records batch search analytics events (query, click, zero_result, synthesis, answer_frame, reformulation, rescue_action).

Accepts a batch of search analytics events for tracking query frequency, click-through rates, zero-result queries, self-serve answer states, reformulations, rescue-action usage, and synthesis usage. Queries and user/session identifiers are pseudonymized before persistence. Fire-and-forget from the client; failures do not affect search functionality.

Responses:

POST /v1/advisory-ai/search/feedback

Submits user feedback (helpful/not_helpful) for a search result or synthesis.

Records a thumbs-up or thumbs-down signal for a specific search result, identified by entity key and domain. Query/user dimensions are pseudonymized for analytics privacy. Fire-and-forget from the UI perspective.

Responses:

GET /v1/advisory-ai/search/history

Returns the authenticated user’s recent search queries.

Returns up to 50 recent search queries for the current user, ordered by recency. Server-side history supplements localStorage-based history in the UI.

Responses:

DELETE /v1/advisory-ai/search/history

Clears the authenticated user’s search history.

Removes all server-side search history entries for the current user and tenant.

Responses:

DELETE /v1/advisory-ai/search/history/{historyId}

Removes a single search history entry.

Removes a specific search history entry by ID for the current user and tenant.

Parameters:

Responses:

GET /v1/advisory-ai/search/quality/alerts

Lists open search quality alerts (zero-result, high negative feedback, fallback loops, abandoned fallback).

Returns search quality alerts ordered by occurrence count. Filterable by status (open, acknowledged, resolved) and alert type (zero_result, high_negative_feedback, fallback_loop, abandoned_fallback). Requires admin scope.

Parameters:

Responses:

PATCH /v1/advisory-ai/search/quality/alerts/{alertId}

Updates a search quality alert status (acknowledge or resolve).

Transitions a search quality alert to acknowledged or resolved status. Optionally includes a resolution description text.

Parameters:

Responses:

GET /v1/advisory-ai/search/quality/metrics

Returns aggregate search quality metrics for the dashboard.

Provides total searches, zero-result rate, average result count, and feedback score for a specified period (24h, 7d, 30d). Requires admin scope.

Parameters:

Responses:

GET /v1/evidence-packs

List evidence packs

Returns a paginated list of evidence packs for the current tenant, optionally filtered by CVE ID or run ID. Supports limit up to 100. Results include pack summaries with subject type, claim count, and evidence count.

Parameters:

Responses:

POST /v1/evidence-packs

Create an evidence pack

Creates a new evidence pack containing AI-generated claims and supporting evidence items for a vulnerability subject. Claims are linked to evidence items by ID. The pack is assigned a content digest for tamper detection and can subsequently be signed via the sign endpoint.

Responses:

GET /v1/evidence-packs/{packId}

Get an evidence pack by ID

Returns the full evidence pack record including all claims, evidence items, subject, context, and related links (sign, verify, export). Access is tenant-scoped; packs from other tenants return 404.

Parameters:

Responses:

GET /v1/evidence-packs/{packId}/export

Export an evidence pack in a specified format

Exports an evidence pack in the requested format. Supported formats: json (default), markdown, html, pdf, signedjson, evidencecard, and evidencecardcompact. The format query parameter controls the output; the appropriate Content-Type and filename are set in the response.

Parameters:

Responses:

POST /v1/evidence-packs/{packId}/sign

Sign an evidence pack

Signs the specified evidence pack using DSSE (Dead Simple Signing Envelope), producing a cryptographic attestation over the pack’s content digest. The resulting signed pack and DSSE envelope are returned and stored for subsequent verification.

Parameters:

Responses:

POST /v1/evidence-packs/{packId}/verify

Verify an evidence pack’s signature and integrity

Verifies the cryptographic signature and content digest of a signed evidence pack. Returns per-evidence URI resolution results, digest match status, and signing key ID. Returns 400 if the pack has not been signed or verification fails.

Parameters:

Responses:

GET /v1/runs/{runId}/evidence-packs

List evidence packs for a run

Returns all evidence packs associated with a specific AI investigation run, filtered to the current tenant. Includes pack summaries with claim count, evidence count, subject type, and CVE ID.

Parameters:

Responses:

POST /v1/search/index/rebuild

Rebuilds unified search index from configured ingestion sources.

Triggers a full unified index rebuild across all registered ingestion adapters (knowledge, findings, vex, policy, platform). Existing domain rows are replaced deterministically.

Responses:

POST /v1/search/query

Searches across all Stella Ops domains with weighted fusion and entity grouping.

Performs a unified search across knowledge base, findings, VEX statements, policy rules, and platform catalog entities. Returns entity-grouped cards with domain-weighted RRF scoring and optional deterministic synthesis. Supports domain/entity-type filtering and ambient context-aware search.

Responses:

POST /v1/search/suggestions/evaluate

Preflights contextual search suggestions against the active corpus.

Evaluates a bounded list of suggested queries without recording user-search analytics so the UI can suppress dead suggestion chips. Returns per-query viability plus aggregate domain coverage for the active context.

Responses:

POST /v1/search/synthesize

Streams deterministic-first search synthesis as SSE.

Produces deterministic synthesis first, then optional LLM synthesis chunks, grounding score, and actions. Requires search synthesis scope and tenant context.

Responses: