Skip to main content

Create a target

A target is the AI system Spectral tests against and the root concept in Spectral.

You can create a target programmatically via POST /api/v1/targets as follows:

Create the target

A target takes three fields:

  • name: a label for the target.
  • description: its Description, the identity and behavioral profile of your system, and a crucial part of how Spectral generates realistic tests. It must be at least 120 characters — give Spectral enough detail to work with.
  • config: the modality how Spectral connects to your system.

Depending on the modality, the request would look as follows:

Request
curl -X POST https://spectral.principled.app/api/v1/targets \
     -H "Authorization: Bearer ak_****" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Support Assistant",
       "description": "Customer support assistant for AcmeShip, a parcel delivery service operating across the UK and Europe. Handles delivery questions, tracking, returns, and refunds for website chat users.",
       "config": {
         "type": "api",
         "endpoint": "https://api.acmeship.com/assistant/chat"
       }
     }'

Whichever modality you choose, a 201 returns the created target:

Response
{
  "id": "9f8c2...",
  "name": "Support Assistant",
  "description": "Customer support assistant for AcmeShip, a parcel delivery service operating across the UK and Europe. Handles delivery questions, tracking, returns, and refunds for website chat users.",
  "type": "api",
  "created_at": "2026-06-18T12:00:00Z",
  "updated_at": "2026-06-18T12:00:00Z"
}

Test the connection (recommended)

Testing the connection is optional but strongly recommended. It confirms Spectral can reach the target before you launch an evaluation, catching a wrong URL, a missing credential, or an unreachable endpoint up front. This is the API equivalent of the Test connection button in the UI.

Request
curl -X POST \
     https://spectral.principled.app/api/v1/targets/9f8c2.../test-connection \
     -H "Authorization: Bearer ak_****"
Response
{
  "status": "success",
  "message": "Connection successful.",
  "retryable": false
}

A status of success means the target is ready. On failure, message explains what went wrong and retryable indicates whether the problem is transient (worth retrying) or a configuration issue you need to fix first.