Core Workflows
Most programmatic use of Spectral follows the same path: create a target, give it a knowledge base to test against, launch an evaluation, then read its results and the individual conversations behind them.
Every request needs an API key. If you haven't generated one yet, start with the Quickstart.
The API and the UI are fully interchangeable: anything you can do in one, you can do in the other. A common split is to set up targets and knowledge bases (steps 1 and 2) in the UI, then launch evaluations and pull back their results (steps 3 and 4) from code. Combine them however suits your workflow.
Create a target
A target is the AI system Spectral tests against and the root concept in Spectral.
Create a targetRegister the system under test and verify Spectral can reach it.Create a knowledge base
A knowledge base is the material Spectral grounds its tests in (your docs, policies, and FAQs), so the scenarios it generates reflect what your system should know.
Create a knowledge baseUpload or crawl the material Spectral grounds its tests in.Launch an evaluation and read the results
Launch an evaluation against the target.
It runs asynchronously: the request returns immediately with a job that you poll until it completes.
Once it does, run GET /api/v1/targets/{targetId}/evaluations/{evaluationId} to fetch the completed evaluation and its rolled-up aggregates.
Query the executions
The aggregates field gives you rolled-up counts, but not the conversations themselves. The executions are the individual graded conversations behind those numbers, each with its message transcript and turn-level judgments. Query them separately to see what happened in each one.