Run span-02

{
  "$ref": "#/components/schemas/Span2DecisionRequest"
}

{
  "$ref": "#/components/schemas/Span2DecisionResponse"
}

{
  "type": "object",
  "additionalProperties": true
}

{
  "type": "object",
  "additionalProperties": true
}

{
  "type": "object",
  "additionalProperties": true
}

{
  "type": "object",
  "additionalProperties": true
}

{
  "type": "object",
  "additionalProperties": true
}

{
  "summary": "Run span-02",
  "operationId": "createDecisions",
  "tags": [
    "Respan Models"
  ],
  "security": [
    {
      "RespanApiKey": []
    }
  ],
  "description": "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.\n\nSet 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.",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Span2DecisionRequest"
        },
        "example": {
          "model": "span-02",
          "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?"
            }
          },
          "reasoning": {
            "mode": "auto"
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Answers keyed by question id. The example is the captured response to the request shown; probabilities can vary slightly between calls.",
      "headers": {
        "X-Respan-Log-Id": {
          "description": "ID of the Respan request log for this call.",
          "schema": {
            "type": "string"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Span2DecisionResponse"
          },
          "example": {
            "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
            }
          }
        }
      }
    },
    "400": {
      "description": "Invalid request: an unknown model, `stream: true`, or questions the model rejects. Correct the request before retrying.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": true
          },
          "example": {
            "detail": "Unknown model `gpt-5.5`. Use `span-02`, or omit `model`."
          }
        }
      }
    },
    "402": {
      "description": "The organization has no Respan credits. Add credits to call span-02.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": true
          }
        }
      }
    },
    "403": {
      "description": "Missing, invalid or expired Respan API key.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": true
          }
        }
      }
    },
    "429": {
      "description": "The organization's span-02 rate limit was reached. Retry with exponential backoff.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": true
          }
        }
      }
    },
    "504": {
      "description": "span-02 didn't answer in time. Retry; if it persists, send fewer questions or a shorter state.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": true
          }
        }
      }
    }
  }
}

{}

{
  "schemas": {
    "Span2DecisionRequest": {
      "type": "object",
      "required": [
        "state",
        "questions"
      ],
      "properties": {
        "model": {
          "type": "string",
          "default": "span-02",
          "description": "Use `span-02` or `respan/span-02`. Omit for `span-02`.",
          "example": "span-02"
        },
        "state": {
          "description": "What the questions are about: text or any JSON value.",
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "object",
              "additionalProperties": true
            },
            {
              "type": "array",
              "items": {}
            }
          ]
        },
        "questions": {
          "type": "object",
          "description": "Your question ids mapped to questions. Answers come back under the same ids.",
          "additionalProperties": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/TypeSafeChoiceQuestion"
              },
              {
                "$ref": "#/components/schemas/TypeSafeNoulQuestion"
              },
              {
                "$ref": "#/components/schemas/TypeSafeScoreQuestion"
              },
              {
                "$ref": "#/components/schemas/Span2NumberQuestion"
              }
            ]
          }
        },
        "images": {
          "type": "array",
          "maxItems": 4,
          "description": "Up to 4 images, as data URIs or base64. span-02 sees them before the text.",
          "items": {
            "type": "string"
          }
        },
        "reasoning": {
          "$ref": "#/components/schemas/Span2Reasoning"
        },
        "respan_params": {
          "type": "object",
          "additionalProperties": true,
          "description": "Respan parameters for the request log, such as `customer_identifier`."
        }
      }
    },
    "Span2DecisionResponse": {
      "type": "object",
      "required": [
        "model",
        "answers"
      ],
      "properties": {
        "model": {
          "type": "string",
          "enum": [
            "span-02"
          ],
          "description": "The model that answered."
        },
        "answers": {
          "type": "object",
          "description": "Answers keyed by the ids in `questions`.",
          "additionalProperties": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/TypeSafeChoiceAnswer"
              },
              {
                "$ref": "#/components/schemas/TypeSafeNoulAnswer"
              },
              {
                "$ref": "#/components/schemas/TypeSafeScoreAnswer"
              },
              {
                "$ref": "#/components/schemas/Span2NumberAnswer"
              }
            ]
          }
        },
        "usage": {
          "type": "object",
          "description": "Billed token counts. Thought tokens aren't billed.",
          "properties": {
            "input_tokens": {
              "type": "integer"
            },
            "output_tokens": {
              "type": "integer"
            }
          }
        }
      }
    },
    "Span2NumberAnswer": {
      "type": "object",
      "required": [
        "type",
        "number",
        "text",
        "confidence"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "number"
          ]
        },
        "number": {
          "type": "number",
          "nullable": true,
          "description": "The answer as a number, or null if the model's text is not a number."
        },
        "text": {
          "type": "string",
          "description": "The answer as the model wrote it."
        },
        "confidence": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "How sure span-02 is of the answer."
        }
      }
    },
    "Span2NumberQuestion": {
      "type": "object",
      "description": "Ask for a number. span-02 answers with the number itself, so no options are listed.",
      "required": [
        "type",
        "instructions"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "number"
          ]
        },
        "instructions": {
          "$ref": "#/components/schemas/TypeSafeEntry"
        }
      }
    },
    "Span2Reasoning": {
      "type": "object",
      "description": "How span-02 thinks before it answers. The thought itself is never returned, and its tokens aren't billed.",
      "properties": {
        "mode": {
          "type": "string",
          "enum": [
            "auto",
            "on",
            "off"
          ],
          "default": "auto",
          "description": "`auto` thinks only when span-02 is unsure, `on` thinks for every question, `off` never thinks."
        },
        "budget_ms": {
          "type": "integer",
          "minimum": 0,
          "maximum": 600000,
          "default": 0,
          "description": "Thinking time for the request in milliseconds. span-02 thinks until then, then answers with its best decision so far. `0` means no deadline; a per-question cap on thought length still applies."
        }
      }
    },
    "TypeSafeChoiceAnswer": {
      "type": "object",
      "required": [
        "type",
        "choice",
        "probabilities",
        "confidence"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "choice"
          ]
        },
        "choice": {
          "type": "string",
          "description": "Selected option name."
        },
        "probabilities": {
          "type": "object",
          "additionalProperties": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          }
        },
        "confidence": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        }
      }
    },
    "TypeSafeChoiceQuestion": {
      "type": "object",
      "description": "Select an option from the supplied criteria.",
      "required": [
        "type",
        "criteria"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "choice"
          ]
        },
        "instructions": {
          "$ref": "#/components/schemas/TypeSafeEntry"
        },
        "criteria": {
          "type": "object",
          "description": "Option names mapped to descriptions. Use null for an option without a description.",
          "additionalProperties": {
            "$ref": "#/components/schemas/TypeSafeEntry"
          },
          "maxProperties": 255
        }
      }
    },
    "TypeSafeContent": {
      "description": "Text or structured context supplied to Jev.",
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "object",
          "additionalProperties": true
        },
        {
          "type": "array",
          "items": {}
        }
      ]
    },
    "TypeSafeEntry": {
      "description": "Question instructions or rubric descriptions. Accepts text, an object, an array, or null. See https://docs.typesafe.ai/primitives/advanced.",
      "oneOf": [
        {
          "type": "string",
          "nullable": true
        },
        {
          "type": "object",
          "additionalProperties": true
        },
        {
          "type": "array",
          "items": {}
        }
      ]
    },
    "TypeSafeNoulAnswer": {
      "type": "object",
      "required": [
        "type",
        "noul"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "noul"
          ]
        },
        "noul": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Probability of yes: 0 means no, 1 means yes."
        }
      }
    },
    "TypeSafeNoulQuestion": {
      "type": "object",
      "description": "A yes/no judgment expressed as a probability.",
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "noul"
          ]
        },
        "instructions": {
          "$ref": "#/components/schemas/TypeSafeEntry"
        },
        "criteria": {
          "type": "object",
          "description": "Optional guidance for yes and no.",
          "properties": {
            "true": {
              "$ref": "#/components/schemas/TypeSafeEntry"
            },
            "false": {
              "$ref": "#/components/schemas/TypeSafeEntry"
            }
          },
          "nullable": true
        }
      }
    },
    "TypeSafeScoreAnswer": {
      "type": "object",
      "required": [
        "type",
        "score",
        "legend",
        "probabilities",
        "confidence"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "score"
          ]
        },
        "score": {
          "type": "number",
          "description": "Probability-weighted level index; may be fractional."
        },
        "legend": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/components/schemas/TypeSafeContent"
          },
          "description": "Level indices mapped to rubric descriptions."
        },
        "probabilities": {
          "type": "object",
          "additionalProperties": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          }
        },
        "confidence": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        }
      }
    },
    "TypeSafeScoreQuestion": {
      "type": "object",
      "description": "Evaluate the state on an ordered rubric.",
      "required": [
        "type",
        "criteria"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "score"
          ]
        },
        "instructions": {
          "$ref": "#/components/schemas/TypeSafeEntry"
        },
        "criteria": {
          "type": "array",
          "minItems": 2,
          "items": {
            "$ref": "#/components/schemas/TypeSafeContent"
          },
          "description": "Rubric levels in order, starting at index 0.",
          "maxItems": 10
        }
      }
    }
  },
  "securitySchemes": {
    "RespanApiKey": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "Respan API key",
      "description": "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.",
      "x-fern-bearer": {
        "name": "respanApiKey",
        "env": "RESPAN_API_KEY"
      }
    }
  }
}