Skip to main content

Generate with AI

Spectral can generate the pieces of a test setup for you rather than making you write them by hand: a target's description, and the tasks, personas, and principles an evaluation runs.

Generate a target description​

A target's description must be at least 120 characters, because Spectral uses it to generate realistic tests. Generate one from a public website instead of writing it yourself:

Request
curl -X POST https://spectral.principled.app/api/v1/targets/generate-description \
     -H "Authorization: Bearer ak_****" \
     -H "Content-Type: application/json" \
     -d '{ "website_url": "https://acmeship.com" }'

The response is a ready-to-use description you can pass straight to Create a target:

Response
{
  "description": "AcmeShip is a parcel delivery service operating across the UK and Europe. Its support assistant handles delivery tracking, returns, and refund questions for website chat users, following the published returns policy."
}

Generate tasks, personas, and principles​

Spectral generates test entities from the content already attached to a target's knowledge base. Each entity type has its own endpoint, and all three take the same body:

Request
curl -X POST https://spectral.principled.app/api/v1/targets/9f8c2.../tasks/generate \
     -H "Authorization: Bearer ak_****" \
     -H "Content-Type: application/json" \
     -d '{
       "num_entities": 10,
       "focus": "COMPLIANCE",
       "maximize_kb_coverage": true
     }'
ParameterDescription
num_entitiesRequired. How many entities to generate.
focusThe dimension to generate for: KNOWLEDGE, COMPLIANCE, or SCOPE.
grounding[Optional] Knowledge scope to generate from; defaults to all resources on the target.
maximize_kb_coverage[Optional] Spread the generated entities across the knowledge base rather than clustering them.
language[Optional] The language to generate in; defaults to English.

Generation runs in the background and returns a job:

Response
{
  "job": {
    "id": "job_gen7a...",
    "status": "queued",
    "kind": "generate_tasks",
    "resource": { "type": "target", "id": "9f8c2..." },
    "created_at": "2026-06-20T12:00:00Z"
  }
}

Poll the job with GET /api/v1/jobs/{job_id} until it succeeds (see Async jobs). The generated entities are then attached to the target, ready to reference by id in a custom evaluation.