Advisory AI API Reference

Audience: platform integrators and automation authors calling the Advisory AI HTTP API.

1. Overview

The Advisory AI service exposes deterministic, guardrail-enforced endpoints for generating advisory summaries, conflict explanations, and remediation plans. Each request is backed by the Aggregation-Only Contract (AOC): inputs originate from immutable Concelier/Excititor evidence and SBOM context, and every output ships with verifiable citations and cache digests.

The surface is gated behind Authority scopes and is designed to operate identically online or offline (local inference profiles).

Related: CLI usage · Evidence payloads (LNM-aligned) · AI attestations and replay · Deployment guide.

2. Base conventions

3. Authentication & scopes

Advisory AI calls must include aoc:verify plus an Advisory AI scope. Authority enforces tenant binding for all combinations.

Requests without aoc:verify are rejected with invalid_scope. Tokens aimed at remote inference profiles must also satisfy tenant consent (requireTenantConsent in Authority config).

4. Profiles & inference selection

Profiles determine which model backend and guardrail stack execute the request. The profile field defaults to default (fips-local).

5. Common request envelope

All task endpoints accept the same JSON payload; taskType is implied by the route.

{
  "advisoryKey": "csaf:redhat:RHSA-2025:1001",
  "artifactId": "registry.stella-ops.internal/runtime/api",
  "artifactPurl": "pkg:oci/runtime-api@sha256:d2c3...",
  "policyVersion": "2025.10.1",
  "profile": "fips-local",
  "preferredSections": ["Summary", "Remediation"],
  "forceRefresh": false
}

Field notes:

• advisoryKey required. Matches the Concelier advisory identifier or VEX statement key.
• artifactId / artifactPurl optional but recommended for remediation tasks (enables SBOM context).
• policyVersion locks evaluation to a specific Policy Engine digest. Omit for “current”.
• profile selects inference profile (see §4). Unknown values return 400.
• preferredSections prioritises advisory sections; the orchestrator still enforces AOC.
• forceRefresh bypasses cache, regenerating output and resealing DSSE bundle.

6. Responses & caching

Successful responses share a common envelope:

{
  "taskType": "Summary",
  "profile": "fips-local",
  "generatedAt": "2025-11-03T18:22:43Z",
  "inputDigest": "sha256:6f3b...",
  "outputHash": "sha256:1d7e...",
  "ttlSeconds": 86400,
  "content": {
    "format": "markdown",
    "body": "### Summary\n1. [Vendor statement][1] ..."
  },
  "citations": [
    {
      "index": 1,
      "kind": "advisory",
      "sourceId": "concelier:csaf:redhat:RHSA-2025:1001:paragraph:12",
      "uri": "https://access.redhat.com/errata/RHSA-2025:1001"
    }
  ],
  "context": {
    "planCacheKey": "adv-summary:csaf:redhat:RHSA-2025:1001:fips-local",
    "chunks": 42,
    "vectorMatches": 12,
    "sbom": {
      "artifactId": "registry.stella-ops.internal/runtime/api",
      "versionTimeline": 8,
      "dependencyPaths": 5,
      "dependencyNodes": 17
    }
  }
}

• content.format is markdown for human-readable payloads; machine-readable JSON attachments will use json. The CLI and Console render Markdown directly.
• citations indexes correspond to bracketed references in the Markdown body.
• context.planCacheKey lets operators resubmit the same request or inspect the plan via GET /v1/advisory-ai/plans/{cacheKey} (optional; available only when plan preview is enabled — see §7.7).
• Cached copies honour tenant-specific TTLs (default 24h). Exceeding TTL triggers regeneration on next request.

7. Endpoints

7.1 POST /v1/advisory-ai/summaries

Generate or retrieve a cached advisory summary. Requires advisory-ai:operate.

• Request body: Common envelope (preferred sections default to Summary).
• Response: Summary output (see §6 example).
• Errors:
  • 400 advisory.summary.missingAdvisoryKey – empty or malformed advisoryKey.
  • 404 advisory.summary.advisoryNotFound – Concelier cannot resolve the advisory, or the tenant is forbidden.
  • 409 advisory.summary.contextUnavailable – SBOM context still indexing; retry later.

7.2 POST /v1/advisory-ai/conflicts

Explain conflicting VEX statements, ranked by trust metadata.

• Additional payload hints: Set preferredSections to include Conflicts or targeted statement IDs.
• Response extensions: content.format remains Markdown; context.conflicts array highlights conflicting statement IDs and trust scores.
• Errors: include 404 advisory.conflict.vexNotFound, 409 advisory.conflict.trustDataPending (waiting on Excititor linksets).

7.3 POST /v1/advisory-ai/remediation

Produce remediation plan with fix versions and verification steps.

• Additional payload hints: Provide artifactId or artifactPurl to unlock SBOM timeline + dependency analysis.
• Response extensions: content.format Markdown plus context.remediation with recommended fix versions (package, fixedVersion, rationale).
• Errors: 422 advisory.remediation.noFixAvailable (vendor has not published fix), 409 advisory.remediation.policyHold (policy forbids automated remediation).

7.4 POST /v1/advisory-ai/remediation/apply

Apply a remediation plan by creating a PR/MR in the target SCM. Requires advisory-ai:operate and tenant SCM connector configuration. GitHub PR bodies are returned only after the SCM connector and repository owner/repo context are valid and the PR is created. Missing connector or invalid repository context returns a failed result without prBody; the service must not emit placeholder PR text.

• Request body:

{
  "planId": "plan-abc123",
  "scmType": "github"
}

• Response:

{
  "prId": "gh-pr-42",
  "prNumber": 42,
  "url": "https://github.com/owner/repo/pull/42",
  "branchName": "stellaops/security-fix/plan-abc123",
  "status": "Open",
  "statusMessage": "Pull request created successfully",
  "prBody": "## Security Remediation\n\n**Plan ID:** `plan-abc123`\n...",
  "createdAt": "2026-01-14T12:00:00Z",
  "updatedAt": "2026-01-14T12:00:00Z"
}

• PR body includes:
  • Summary with vulnerability and component info
  • Remediation steps (file changes)
  • Expected SBOM changes (upgrades, additions, removals)
  • Test requirements
  • Rollback steps
  • VEX claim context
  • Evidence references
• Supported SCM types: github, gitlab, azure-devops, gitea
• Errors:
  • 404 remediation.planNotFound – plan does not exist
  • 400 remediation.scmTypeNotSupported – requested SCM type not configured
  • 409 remediation.planNotReady – plan is not PR-ready (see notReadyReason)
  • 502 remediation.scmError – SCM connector error (branch/file/PR creation failed)

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

Check the status of a PR created by the remediation apply endpoint.

• Query parameters: scmType (optional, defaults to github)
• Response: Same envelope as POST /remediation/apply only when the SCM adapter has persisted repository context for the PR.
• Errors: 404 remediation.prNotFound, 503 remediation.prStatusUnavailable when the PR id has no connector-backed repository context. The GitHub adapter must not synthesize statuses such as “waiting for CI”.

7.6 GET /v1/advisory-ai/outputs/{outputHash}

Fetch cached artefact (same envelope as §6). Requires advisory-ai:view.

• Headers: Supports If-None-Match with the outputHash (Etag) for cache validation.
• Errors: 404 advisory.output.notFound if cache expired or tenant lacks access.

7.7 GET /v1/advisory-ai/plans/{cacheKey} (optional)

When plan preview is enabled (feature flag advisoryAi.planPreview.enabled), this endpoint returns the orchestration plan using AdvisoryPipelinePlanResponse (task metadata, chunk/vector counts). Requires advisory-ai:operate.

7.8 LLM adapter exposure

Advisory AI exposes a unified adapter surface for provider discovery and OpenAI-compatible completion calls.

• GET /v1/advisory-ai/adapters/llm/providers
• POST /v1/advisory-ai/adapters/llm/{providerId}/chat/completions
• POST /v1/advisory-ai/adapters/openai/v1/chat/completions (alias for providerId=openai)

Scope requirements (enforced by the canonical named policies — see architecture.md §8):

• Read/discovery: advisory-ai:view (also satisfied by advisory-ai:operate / advisory-ai:admin)
• Invoke/completion: advisory-ai:operate (also satisfied by advisory-ai:admin)

Historical note: earlier builds layered a dead inner advisory:adapter:read / advisory:adapter:invoke / advisory:openai:* / advisory:{providerId}:invoke / advisory:run check under the named policy. Those strings were never registered Authority scopes and were granted to no client, so the inner AND gate made these endpoints unreachable even for a valid advisory-ai:operate caller. The dead inner check was removed; the named policies are the sole gate.

Operational notes:

• Adapter endpoints are disabled by default and must be explicitly enabled by config.
• stream=true is currently rejected on adapter completion endpoints.
• Provider discovery returns configuration/validation/exposure state per provider so operators can verify whether openai is configured before traffic cutover.

Runtime config keys:

• AdvisoryAI:Adapters:Llm:Enabled (env ADVISORYAI__AdvisoryAI__Adapters__Llm__Enabled)
• AdvisoryAI:LlmProviders:ConfigDirectory (env ADVISORYAI__AdvisoryAI__LlmProviders__ConfigDirectory)

Gateway exposure paths:

• /v1/advisory-ai/adapters
• /api/v1/advisory-ai/adapters

7.9 Knowledge search

Deterministic retrieval API for docs, OpenAPI operations, and Doctor checks.

• POST /v1/advisory-ai/search
• POST /v1/advisory-ai/index/rebuild

Scope notes:

• Search: one of advisory:run, advisory:search, advisory:read.
• Rebuild: one of advisory:run, advisory:admin, advisory:index:write.

Search request:

{
  "q": "docker login fails with x509 unknown authority",
  "k": 10,
  "filters": {
    "type": ["docs", "doctor"],
    "product": "stella-ops",
    "version": "2026.02",
    "service": "gateway",
    "tags": ["troubleshooting", "tls"]
  },
  "includeDebug": false
}

Search response contains only grounded results with source actions:

• docs: { path, anchor, spanStart, spanEnd }
• api: { service, method, path, operationId }
• doctor: { checkCode, severity, canRun, runCommand }

Rebuild response:

{
  "documentCount": 12034,
  "chunkCount": 68291,
  "apiSpecCount": 41,
  "apiOperationCount": 2132,
  "doctorProjectionCount": 84,
  "durationMs": 8245
}

8. Error model

Errors follow a standard problem+JSON envelope:

{
  "status": 400,
  "code": "advisory.summary.missingAdvisoryKey",
  "message": "advisoryKey must be provided",
  "traceId": "01HECAJ6RE8T5H4P6Q0XZ7ZD4T",
  "retryAfter": 30
}

All errors include traceId for cross-service correlation and log search.

9. Rate limiting & quotas

Advisory AI honours per-tenant quotas configured under advisoryAi.rateLimits:

• Default: 30 summary/conflict requests per minute per tenant & profile.
• Remediation requests default to 10/minute due to heavier SBOM analysis.
• Cached GET /outputs/{outputHash} calls share the advisory-ai:view bucket (60/minute).

Limits are enforced at the gateway; the API returns 429 with standard Retry-After seconds. Operators can adjust limits via Authority configuration bundles and propagate offline using the Offline Kit.

10. Observability & audit

• Metrics: advisory_ai_requests_total (labelled by tenant, task, profile), advisory_ai_latency_seconds, advisory_ai_validation_failures_total, and advisory_ai_cache_hits_total.
• Logs: Structured with traceId, tenant, task, profile, outputHash, cacheStatus (hit|miss|bypass). Prompt bodies are never logged; guardrail violations emit sanitized snippets only.
• Audit events: advisory_ai.output.generated, advisory_ai.output.accessed, advisory_ai.guardrail.blocked ship to the Authority audit stream with tenant + actor metadata.

11. Offline & sovereignty considerations

• Offline installations bundle prompt templates, guardrail configs, and local model weights. Remote profiles (cloud-openai) remain disabled unless operators explicitly enable them and record consent per tenant.
• Cached outputs include DSSE attestations when DSSE mode is enabled. Export Center ingests cached artefacts via GET /outputs/{outputHash} using advisory-ai:view.
• Force-refresh regenerates outputs using the same cache key, allowing auditors to replay evidence during compliance reviews.

12. Change log