Run span-02 | Respan Docs

curl -X POST https://api.respan.ai/api/v1/decisions \
     -H "Authorization: Bearer <respanApiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "state": {
    "customer_message": "My package arrived damaged and nobody answers my emails. I want a refund now.",
    "order": {
      "id": 123,
      "days_late": 4
    }
  },
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this ticket?",
      "criteria": {
        "returns": "Exchanges, wrong or damaged items",
        "shipping": "Delivery status, delays, lost packages",
        "billing": "Charges, invoices, payment problems"
      }
    },
    "wants_refund": {
      "type": "noul",
      "instructions": "Does the customer ask for a refund?"
    },
    "frustration": {
      "type": "score",
      "instructions": "How frustrated is the customer?",
      "criteria": [
        "Calm or positive",
        "Mildly annoyed",
        "Angry or threatening to leave"
      ]
    },
    "days_late": {
      "type": "number",
      "instructions": "How many days late is the order?"
    }
  },
  "model": "span-02",
  "reasoning": {
    "mode": "auto"
  }
}'

{
  "model": "span-02",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "returns",
      "confidence": 0.969893,
      "probabilities": {
        "returns": 0.9799287,
        "shipping": 0.012929817,
        "billing": 0.00714149
      }
    },
    "wants_refund": {
      "type": "noul",
      "noul": 0.99997675
    },
    "frustration": {
      "type": "score",
      "score": 1.9921819,
      "legend": {
        "0": "Calm or positive",
        "1": "Mildly annoyed",
        "2": "Angry or threatening to leave"
      },
      "probabilities": {
        "0": 0.00009271287,
        "1": 0.0076327343,
        "2": 0.9922746
      },
      "confidence": 0.9882728
    },
    "days_late": {
      "type": "number",
      "number": 4,
      "text": "4",
      "confidence": 0.9999089
    }
  },
  "usage": {
    "input_tokens": 580,
    "output_tokens": 1
  }
}

Answer typed questions about a state with span-02, Respan’s decision model. Each question is choice, noul (yes/no), score or number, and each answer carries its probability distribution and confidence. One request can mix all four types.

Set a thinking deadline with reasoning.budget_ms: span-02 thinks until then and answers with its best decision so far. The body is the System One format, so a System One client works by changing the URL. span-02 runs on Respan credits only and is priced per input and output token; thought tokens aren’t billed. Streaming is unsupported.

Authentication

AuthorizationBearer

Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.

Request

This endpoint expects an object.

statestring or map from strings to any or list of anyRequired

What the questions are about: text or any JSON value.

questionsmap from strings to objectsRequired

Your question ids mapped to questions. Answers come back under the same ids.

modelstringOptionalDefaults to span-02

Use span-02 or respan/span-02. Omit for span-02.

imageslist of stringsOptional

Up to 4 images, as data URIs or base64. span-02 sees them before the text.

reasoningobjectOptional

How span-02 thinks before it answers. The thought itself is never returned, and its tokens aren’t billed.

respan_paramsmap from strings to anyOptional

Respan parameters for the request log, such as customer_identifier.

Response headers

X-Respan-Log-IdstringOptional

ID of the Respan request log for this call.

Response

Answers keyed by question id. The example is the captured response to the request shown; probabilities can vary slightly between calls.

modelenum

The model that answered.

Allowed values:

answersmap from strings to objects

Answers keyed by the ids in questions.

usageobjectOptional

Billed token counts. Thought tokens aren't billed.

Errors

400

Bad Request Error

402

Payment Required Error

403

Forbidden Error

429

Too Many Requests Error

504

Gateway Timeout Error