Behaviour Specs

A behaviour spec is the core entity in Tuned Tensor — a structured description of the model behaviour you want to achieve.

The Behaviour Spec Object

{
  "id": "cafd8799-9180-482e-b0b2-c46d08e4b045",
  "name": "Customer Support Bot",
  "description": "Handles billing and support questions",
  "system_prompt": "You are a helpful support agent...",
  "guidelines": ["Be concise", "Show empathy"],
  "constraints": ["Never promise refunds"],
  "examples": [
    { "input": "How do I cancel?", "output": "Go to Settings > Billing..." }
  ],
  "base_model": "Qwen/Qwen3.5-2B",
  "created_at": "2026-03-06T08:27:33.492Z",
  "updated_at": "2026-03-06T08:27:33.492Z"
}

The recommended way to work with specs is the tt CLI — each endpoint below shows the tt command first, followed by the equivalent REST call.

Create a Behaviour Spec

POST /api/v1/behavior-specs

CLI

# Scaffold + push a local spec file
tt init --name "Customer Support Bot" --model Qwen/Qwen3.5-2B
# edit tunedtensor.json, then:
tt push

# Or create directly from an existing file
tt specs create --file spec.json

Equivalent REST call

curl -X POST https://tunedtensor.com/api/v1/behavior-specs \
  -H "Authorization: Bearer tt_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Bot",
    "system_prompt": "You are a helpful support agent...",
    "guidelines": ["Be concise"],
    "constraints": ["Never promise refunds"],
    "examples": [
      {"input": "How do I cancel?", "output": "Go to Settings > Billing..."}
    ],
    "base_model": "Qwen/Qwen3.5-2B"
  }'

Required: name, examples (at least 1). Optional: description, system_prompt, guidelines, constraints, base_model (defaults to Qwen/Qwen3.5-2B). Supported fine-tuning base models are Qwen/Qwen3.5-2B, Qwen/Qwen3.5-4B, google/gemma-4-E2B-it, google/gemma-4-E4B-it, meta-llama/Llama-3.2-3B-Instruct, microsoft/Phi-4-mini-instruct, ibm-granite/granite-3.3-2b-instruct, and bigcode/starcoder2-3b.

List Behaviour Specs

GET /api/v1/behavior-specs

CLI

tt specs list

Equivalent REST call

curl https://tunedtensor.com/api/v1/behavior-specs \
  -H "Authorization: Bearer tt_your_api_key"

Returns a paginated list. Each spec includes _run_count, _latest_run_status, and _latest_run_score.

Get a Behaviour Spec

GET /api/v1/behavior-specs/:id

CLI

tt specs get cafd8799-...

Equivalent REST call

curl https://tunedtensor.com/api/v1/behavior-specs/cafd8799-... \
  -H "Authorization: Bearer tt_your_api_key"

Returns the full spec plus _runs array and _run_count.

Update a Behaviour Spec

PUT /api/v1/behavior-specs/:id

CLI

# Edit tunedtensor.json and push — tt push performs an update when the
# local file contains the id saved by the first tt push
tt push

# Or patch directly from a JSON file
tt specs update cafd8799-... --file updates.json

Equivalent REST call

curl -X PUT https://tunedtensor.com/api/v1/behavior-specs/cafd8799-... \
  -H "Authorization: Bearer tt_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "examples": [
      ...existing examples...,
      {"input": "New question", "output": "New answer"}
    ]
  }'

All fields are optional. Only included fields are updated. When updating examples, send the full array.

Delete a Behaviour Spec

DELETE /api/v1/behavior-specs/:id

CLI

tt specs delete cafd8799-...

Equivalent REST call

curl -X DELETE https://tunedtensor.com/api/v1/behavior-specs/cafd8799-... \
  -H "Authorization: Bearer tt_your_api_key"

Cascade-deletes all associated runs and eval results.