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: how Spectral connects to your system. Its type field selects the modality, and for endpoint-based targets it also fixes the protocol Spectral speaks:

`config.type`	Connects to	Protocol
`api`	An HTTP endpoint	OpenAI Chat Completions
`responses_api`	An HTTP endpoint	OpenAI Responses API
`ui`	A web chat interface	Browser automation
`internal`	A private system via Spectral Bridge	Responses (default) or Chat Completions

tip

Not sure how to fill these in? Spectral can generate a description from your website.

Depending on the type, the request and its 201 response look as follows:

An api target connects to an HTTP endpoint that speaks the OpenAI Chat Completions contract (POST /v1/chat/completions):

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"
       }
     }'

{
  "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.

curl -X POST \
     https://spectral.principled.app/api/v1/targets/9f8c2.../test-connection \
     -H "Authorization: Bearer ak_****"

{
  "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.