Skip to main content
Version: 2026-08-04

Spectral Public API

The Spectral API gives you programmatic access to everything in the Spectral app, over HTTP. This reference documents every endpoint; the conventions below apply to all of them.

Resource model​

Almost every resource is scoped to a target, an AI system under test. A typical integration walks one path down the tree:

  • Targets: register a system to test, and check connectivity before you run anything.
  • Knowledge bases: ground a target in your own content by crawling a site, supplying a URL list, or uploading files.
  • Tasks, principles, principle categories, and personas: the reusable building blocks you assemble into a custom evaluation.
  • Evaluations: generate and grade conversations against a target. Autopilot builds the test spec for you, custom assembles it from your own entities, and forensic judges conversations you already have.
  • Executions: the individual graded conversations an evaluation produces.
  • Reports: shareable summaries rolled up from an evaluation or a set of executions.

Requests​

Every path is relative to a single versioned base URL:

https://spectral.principled.app/api/v1

Authenticate every request with your organization-scoped API key as a bearer token. Request and response bodies are JSON, with snake_case field names. Keys belong to a single organization; resources owned by another organization return 404 (never 403), so an id either resolves within your org or does not exist to you.

Pagination and async operations​

List endpoints are cursor-paginated. Operations that start background work return a job you poll until it finishes. See Pagination and Async jobs.

Errors​

Errors share one JSON shape:

{ "code": "string", "message": "string", "context": {}, "retryable": false }

code is machine-readable and the set is open, so handle unknown codes gracefully and fall back to message. Standard HTTP statuses apply: 400 (bad request), 401 (authentication), 404 (not found, including cross-org ids), 409 (state conflict), and 422 (validation, with field-level problems under details.errors).

Authentication​

Spectral API key (org-scoped).

Security Scheme Type:

http

HTTP Authorization Scheme:

bearer