> ## Documentation Index
> Fetch the complete documentation index at: https://read.sqwish.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a prediction

> Answer typed questions about a shared text or JSON-object context.

A successful response includes ordered answers and the actual charge. Both
are durably saved before returning 200. Reuse the same Idempotency-Key and
request after a timeout to recover the result without another charge.



## OpenAPI

````yaml /openapi.json post /v1/predictions
openapi: 3.1.0
info:
  description: >-
    Synchronous structured predictions. Reuse Idempotency-Key for retries.
    Prices are USD decimal strings.
  title: D1 Prediction API
  version: 1.0.0
servers:
  - url: https://d1-staging-5gh8d.ondigitalocean.app
    description: Invited staging — simulated predictions and test credit
security:
  - APIKey: []
paths:
  /v1/predictions:
    post:
      tags:
        - Predictions
      summary: Create a prediction
      description: >-
        Answer typed questions about a shared text or JSON-object context.


        A successful response includes ordered answers and the actual charge.
        Both

        are durably saved before returning 200. Reuse the same Idempotency-Key
        and

        request after a timeout to recover the result without another charge.
      operationId: predict_v1_predictions_post
      parameters:
        - description: >-
            Optional, recommended unique operation key (at most 200 characters).
            Keep the same key and request for retries after a lost response.
            Changed content conflicts; accepted terminal results replay for 24
            hours by default, followed by a tombstone until 30 days from
            acceptance. Never recycle a key for a new logical operation.
          in: header
          name: Idempotency-Key
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Optional, recommended unique operation key (at most 200
              characters). Keep the same key and request for retries after a
              lost response. Changed content conflicts; accepted terminal
              results replay for 24 hours by default, followed by a tombstone
              until 30 days from acceptance. Never recycle a key for a new
              logical operation.
            title: Idempotency-Key
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PredictionInput'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PredictionResponse'
          description: Successful Response
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Malformed or ambiguous JSON.
          headers:
            Retry-After:
              description: When present, wait this many seconds before retrying.
              schema:
                minimum: 1
                type: integer
            X-Request-ID:
              description: Server request identifier for support and correlation.
              schema:
                type: string
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Missing, invalid, or revoked API key.
          headers:
            Retry-After:
              description: When present, wait this many seconds before retrying.
              schema:
                minimum: 1
                type: integer
            X-Request-ID:
              description: Server request identifier for support and correlation.
              schema:
                type: string
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Insufficient available credit.
          headers:
            Retry-After:
              description: When present, wait this many seconds before retrying.
              schema:
                minimum: 1
                type: integer
            X-Request-ID:
              description: Server request identifier for support and correlation.
              schema:
                type: string
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Account is waitlisted or suspended.
          headers:
            Retry-After:
              description: When present, wait this many seconds before retrying.
              schema:
                minimum: 1
                type: integer
            X-Request-ID:
              description: Server request identifier for support and correlation.
              schema:
                type: string
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Resource not found.
          headers:
            Retry-After:
              description: When present, wait this many seconds before retrying.
              schema:
                minimum: 1
                type: integer
            X-Request-ID:
              description: Server request identifier for support and correlation.
              schema:
                type: string
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: >-
            Operation conflict, in-progress request, expired replay, or
            cancellation.
          headers:
            Retry-After:
              description: When present, wait this many seconds before retrying.
              schema:
                minimum: 1
                type: integer
            X-Request-ID:
              description: Server request identifier for support and correlation.
              schema:
                type: string
        '413':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Request exceeds a body, input, or model limit.
          headers:
            Retry-After:
              description: When present, wait this many seconds before retrying.
              schema:
                minimum: 1
                type: integer
            X-Request-ID:
              description: Server request identifier for support and correlation.
              schema:
                type: string
        '415':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Unsupported media type or content encoding.
          headers:
            Retry-After:
              description: When present, wait this many seconds before retrying.
              schema:
                minimum: 1
                type: integer
            X-Request-ID:
              description: Server request identifier for support and correlation.
              schema:
                type: string
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Request validation failed or model is unavailable.
          headers:
            Retry-After:
              description: When present, wait this many seconds before retrying.
              schema:
                minimum: 1
                type: integer
            X-Request-ID:
              description: Server request identifier for support and correlation.
              schema:
                type: string
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Account request, token, concurrency, or read limit exceeded.
          headers:
            Retry-After:
              description: When present, wait this many seconds before retrying.
              schema:
                minimum: 1
                type: integer
            X-Request-ID:
              description: Server request identifier for support and correlation.
              schema:
                type: string
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: >-
            Unexpected service error; replay a prediction to resolve
            uncertainty.
          headers:
            Retry-After:
              description: When present, wait this many seconds before retrying.
              schema:
                minimum: 1
                type: integer
            X-Request-ID:
              description: Server request identifier for support and correlation.
              schema:
                type: string
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Invalid model output; no charge is settled.
          headers:
            Retry-After:
              description: When present, wait this many seconds before retrying.
              schema:
                minimum: 1
                type: integer
            X-Request-ID:
              description: Server request identifier for support and correlation.
              schema:
                type: string
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Service paused, capacity exhausted, or dependency unavailable.
          headers:
            Retry-After:
              description: When present, wait this many seconds before retrying.
              schema:
                minimum: 1
                type: integer
            X-Request-ID:
              description: Server request identifier for support and correlation.
              schema:
                type: string
        '504':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Prediction deadline exceeded; replay using the same operation key.
          headers:
            Retry-After:
              description: When present, wait this many seconds before retrying.
              schema:
                minimum: 1
                type: integer
            X-Request-ID:
              description: Server request identifier for support and correlation.
              schema:
                type: string
components:
  schemas:
    PredictionInput:
      additionalProperties: false
      properties:
        context:
          anyOf:
            - type: string
            - additionalProperties:
                $ref: '#/components/schemas/JsonValue'
              type: object
          title: Context
        model:
          default: default
          maxLength: 128
          minLength: 1
          pattern: ^[A-Za-z0-9_.-]+$
          title: Model
          type: string
        questions:
          items:
            discriminator:
              mapping:
                binary:
                  $ref: '#/components/schemas/BinaryQuestion'
                choice:
                  $ref: '#/components/schemas/ChoiceQuestion'
                score:
                  $ref: '#/components/schemas/ScoreQuestion'
              propertyName: type
            oneOf:
              - $ref: '#/components/schemas/BinaryQuestion'
              - $ref: '#/components/schemas/ChoiceQuestion'
              - $ref: '#/components/schemas/ScoreQuestion'
          maxItems: 16
          minItems: 1
          title: Questions
          type: array
      required:
        - context
        - questions
      title: PredictionInput
      type: object
    PredictionResponse:
      additionalProperties: false
      properties:
        answers:
          items:
            discriminator:
              mapping:
                binary:
                  $ref: '#/components/schemas/BinaryAnswer'
                choice:
                  $ref: '#/components/schemas/ChoiceAnswer'
                score:
                  $ref: '#/components/schemas/ScoreAnswer'
              propertyName: type
            oneOf:
              - $ref: '#/components/schemas/BinaryAnswer'
              - $ref: '#/components/schemas/ChoiceAnswer'
              - $ref: '#/components/schemas/ScoreAnswer'
          title: Answers
          type: array
        model:
          maxLength: 128
          minLength: 1
          pattern: ^[A-Za-z0-9_.-]+$
          title: Model
          type: string
        request_id:
          maxLength: 128
          minLength: 1
          pattern: ^[A-Za-z0-9_.-]+$
          title: Request Id
          type: string
        usage:
          $ref: '#/components/schemas/Usage'
      required:
        - request_id
        - model
        - answers
        - usage
      title: PredictionResponse
      type: object
    ErrorEnvelope:
      additionalProperties: false
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
      required:
        - error
      title: ErrorEnvelope
      type: object
    JsonValue: {}
    BinaryQuestion:
      additionalProperties: false
      properties:
        id:
          maxLength: 128
          minLength: 1
          pattern: ^[A-Za-z0-9_.-]+$
          title: Id
          type: string
        prompt:
          maxLength: 262144
          minLength: 1
          title: Prompt
          type: string
        type:
          const: binary
          title: Type
          type: string
      required:
        - id
        - prompt
        - type
      title: BinaryQuestion
      type: object
    ChoiceQuestion:
      additionalProperties: false
      properties:
        id:
          maxLength: 128
          minLength: 1
          pattern: ^[A-Za-z0-9_.-]+$
          title: Id
          type: string
        options:
          items:
            $ref: '#/components/schemas/Option'
          maxItems: 32
          minItems: 2
          title: Options
          type: array
        prompt:
          maxLength: 262144
          minLength: 1
          title: Prompt
          type: string
        type:
          const: choice
          title: Type
          type: string
      required:
        - id
        - prompt
        - type
        - options
      title: ChoiceQuestion
      type: object
    ScoreQuestion:
      additionalProperties: false
      properties:
        id:
          maxLength: 128
          minLength: 1
          pattern: ^[A-Za-z0-9_.-]+$
          title: Id
          type: string
        levels:
          items:
            maxLength: 262144
            minLength: 1
            type: string
          maxItems: 10
          minItems: 2
          title: Levels
          type: array
        prompt:
          maxLength: 262144
          minLength: 1
          title: Prompt
          type: string
        type:
          const: score
          title: Type
          type: string
      required:
        - id
        - prompt
        - type
        - levels
      title: ScoreQuestion
      type: object
    BinaryAnswer:
      additionalProperties: false
      properties:
        id:
          maxLength: 128
          minLength: 1
          pattern: ^[A-Za-z0-9_.-]+$
          title: Id
          type: string
        probability_true:
          maximum: 1
          minimum: 0
          title: Probability True
          type: number
        type:
          const: binary
          default: binary
          title: Type
          type: string
      required:
        - id
        - probability_true
      title: BinaryAnswer
      type: object
    ChoiceAnswer:
      additionalProperties: false
      properties:
        id:
          maxLength: 128
          minLength: 1
          pattern: ^[A-Za-z0-9_.-]+$
          title: Id
          type: string
        options:
          items:
            $ref: '#/components/schemas/OptionProbability'
          title: Options
          type: array
        selected:
          maxLength: 128
          minLength: 1
          pattern: ^[A-Za-z0-9_.-]+$
          title: Selected
          type: string
        type:
          const: choice
          default: choice
          title: Type
          type: string
      required:
        - id
        - options
        - selected
      title: ChoiceAnswer
      type: object
    ScoreAnswer:
      additionalProperties: false
      properties:
        id:
          maxLength: 128
          minLength: 1
          pattern: ^[A-Za-z0-9_.-]+$
          title: Id
          type: string
        type:
          const: score
          default: score
          title: Type
          type: string
        value:
          title: Value
          type: number
      required:
        - id
        - value
      title: ScoreAnswer
      type: object
    Usage:
      additionalProperties: false
      properties:
        cost_usd:
          pattern: ^\d+\.\d{9}$
          title: Cost Usd
          type: string
        input_tokens:
          minimum: 0
          title: Input Tokens
          type: integer
        metering_version:
          maxLength: 128
          minLength: 1
          pattern: ^[A-Za-z0-9_.-]+$
          title: Metering Version
          type: string
        pricing_version:
          maxLength: 128
          minLength: 1
          pattern: ^[A-Za-z0-9_.-]+$
          title: Pricing Version
          type: string
      required:
        - input_tokens
        - cost_usd
        - metering_version
        - pricing_version
      title: Usage
      type: object
    ErrorDetail:
      additionalProperties: false
      properties:
        code:
          title: Code
          type: string
        message:
          title: Message
          type: string
        request_id:
          title: Request Id
          type: string
      required:
        - code
        - message
        - request_id
      title: ErrorDetail
      type: object
    Option:
      additionalProperties: false
      properties:
        description:
          maxLength: 262144
          minLength: 1
          title: Description
          type: string
        id:
          maxLength: 128
          minLength: 1
          pattern: ^[A-Za-z0-9_.-]+$
          title: Id
          type: string
      required:
        - id
        - description
      title: Option
      type: object
    OptionProbability:
      additionalProperties: false
      properties:
        id:
          maxLength: 128
          minLength: 1
          pattern: ^[A-Za-z0-9_.-]+$
          title: Id
          type: string
        probability:
          maximum: 1
          minimum: 0
          title: Probability
          type: number
      required:
        - id
        - probability
      title: OptionProbability
      type: object
  securitySchemes:
    APIKey:
      scheme: bearer
      type: http

````