Telnyx Decision Models API

openapi: 3.2.0
info:
  version: 2.0.0
  x-latency-category: responsive
  x-endpoint-cost: light
  title: Telnyx Decision Models API
  description: SIP trunking, SMS, MMS, Call Control and Telephony Data Services.
  contact:
    email: support@telnyx.com
servers:
- url: https://api.telnyx.com/v2
  description: Version 2.0.0 of the Telnyx API
security:
- bearerAuth: []
tags:
- name: Decision Models
  description: Beta API for evaluating shared context with typed questions and structured answers using Flash or Pro.
paths:
  /ai/typesafe/v1/systemone:
    post:
      tags:
      - Decision Models
      summary: Evaluate decision models (TypeSafe-compatible)
      description: '**Beta API.** Choose telnyx/decision-flash for the lowest cost and latency, or telnyx/decision-pro for decisions that require long context, including inputs beyond Jev’s 32k per-decision limit. Omitted model defaults to telnyx/decision-flash.


        Evaluate shared context using named choice, noul (yes/no), and score questions. Returns TypeSafe System One-compatible answer shapes, the selected public model alias, and token usage. See the decision model guide for examples and compatibility limits.


        The supported request subset requires instructions for every question, string descriptions for criteria (or null for choice descriptions), 1–64 questions, and 2–64 options for choice and score questions. The model field accepts only telnyx/decision-flash or telnyx/decision-pro. Unsupported model values and unknown fields are rejected. The endpoint is synchronous and does not stream.


        Use the TypeSafe Python SDK with base_url set to https://api.telnyx.com/v2/ai/typesafe and a Telnyx API key. The SDK appends /v1/systemone; explicitly set model to a supported Telnyx alias because its own default model is not supported. Compatibility covers this operation and the documented request subset; it does not include TypeSafe model listing. Scores describe relative preference, not calibrated correctness.'
      operationId: create_typesafe_systemone
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DecisionModelRequest'
            example:
              model: telnyx/decision-flash
              state: Our production calls are failing. Every customer is affected.
              questions:
                team:
                  type: choice
                  instructions: Choose the team that should handle this incident.
                  criteria:
                    billing: Payments and refunds
                    technical_support: Service faults and technical problems
                    sales: New purchases
                production_incident:
                  type: noul
                  instructions: Does the message describe an active production incident?
                urgency:
                  type: score
                  instructions: Rate operational urgency.
                  criteria:
                  - Low
                  - Normal
                  - High
                  - Critical
      responses:
        '200':
          description: All questions evaluated successfully. The response is a complete JSON object, not a stream.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionModelResponse'
              example:
                model: telnyx/decision-flash
                answers:
                  team:
                    type: choice
                    choice: technical_support
                    probabilities:
                      billing: 0.0024719786572585446
                      technical_support: 0.9972674768333701
                      sales: 0.00026054450937119613
                    confidence: 0.9820522416354122
                  production_incident:
                    type: noul
                    noul: 0.9991959141264766
                  urgency:
                    type: score
                    score: 2.9974242859177265
                    legend:
                      '0': Low
                      '1': Normal
                      '2': High
                      '3': Critical
                    probabilities:
                      '0': 0.0003348349100603869
                      '1': 3.529133987660637e-05
                      '2': 0.0015006266723396524
                      '3': 0.9981292470777234
                    confidence: 0.9894200002646713
                usage:
                  input_tokens: 267
                  output_tokens: 4
        '401':
          description: Unauthorized. Supply a valid Telnyx API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionModelError'
              example:
                error:
                  message: Authentication required.
        '413':
          description: Request body is too large or incomplete. Reduce or fix the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionModelError'
              example:
                error:
                  message: Request body too large.
        '422':
          description: Invalid schema or input token limit exceeded. Correct or split the request before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionModelError'
              example:
                error:
                  message: Question "team" requires instructions.
        '429':
          description: Too many requests. Reduce concurrency and retry with backoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionModelError'
              example:
                error:
                  message: Too many requests.
          headers:
            Retry-After:
              description: When present, wait this many seconds before retrying.
              schema:
                type: integer
                minimum: 0
        '502':
          description: The scoring service failed. Retry with bounded backoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionModelError'
              example:
                error:
                  message: Scoring service failed.
        '503':
          description: The decision model service is unavailable. Retry with bounded backoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionModelError'
              example:
                error:
                  message: Decision model service unavailable.
          headers:
            Retry-After:
              description: When present, wait this many seconds before retrying.
              schema:
                type: integer
                minimum: 0
        '504':
          description: Evaluation deadline exceeded. Reduce request size or concurrency before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionModelError'
              example:
                error:
                  message: Evaluation deadline exceeded.
        '529':
          description: The decision model service is at capacity. Retry with bounded backoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionModelError'
              example:
                error:
                  message: Decision model service at capacity.
          headers:
            Retry-After:
              description: When present, wait this many seconds before retrying.
              schema:
                type: integer
                minimum: 0
      x-beta: true
components:
  schemas:
    DecisionModelContent:
      description: Text, a JSON object, or an array containing text-based context. Text-only conversation histories are supported; image and audio inputs are not supported.
      oneOf:
      - type: string
      - type: object
        additionalProperties: true
      - type: array
        items: {}
    DecisionModelProbabilities:
      type: object
      description: Relative scores normalized across the supplied options, summing approximately to 1. These are not calibrated probabilities of correctness.
      minProperties: 2
      maxProperties: 64
      additionalProperties:
        type: number
        minimum: 0
        maximum: 1
    DecisionModelScoreQuestion:
      type: object
      description: Rate the state against an ordered rubric.
      properties:
        type:
          type: string
          description: Question type.
          enum:
          - score
        instructions:
          $ref: '#/components/schemas/DecisionModelContent'
          description: Required instructions describing what to decide about the shared state.
        criteria:
          type: array
          description: Between 2 and 64 description strings in ascending score order. Indices start at zero.
          minItems: 2
          maxItems: 64
          items:
            type: string
      required:
      - type
      - instructions
      - criteria
      additionalProperties: false
      example:
        type: score
        instructions: Rate operational urgency.
        criteria:
        - Low
        - Normal
        - High
        - Critical
    DecisionModelResponse:
      type: object
      description: A complete synchronous evaluation. Answers are returned directly without a data wrapper.
      properties:
        model:
          type: string
          description: Public model alias used to evaluate the request. Returns telnyx/decision-flash when model was omitted. The underlying model is managed by Telnyx.
          readOnly: true
          enum:
          - telnyx/decision-flash
          - telnyx/decision-pro
          example: telnyx/decision-flash
        answers:
          type: object
          description: Answers keyed by exactly the question IDs in the request. Each answer type matches its question.
          minProperties: 1
          maxProperties: 64
          additionalProperties:
            $ref: '#/components/schemas/DecisionModelAnswer'
        usage:
          $ref: '#/components/schemas/DecisionModelUsage'
      required:
      - model
      - answers
      - usage
      additionalProperties: false
      example:
        model: telnyx/decision-flash
        answers:
          team:
            type: choice
            choice: technical_support
            probabilities:
              billing: 0.0024719786572585446
              technical_support: 0.9972674768333701
              sales: 0.00026054450937119613
            confidence: 0.9820522416354122
          production_incident:
            type: noul
            noul: 0.9991959141264766
          urgency:
            type: score
            score: 2.9974242859177265
            legend:
              '0': Low
              '1': Normal
              '2': High
              '3': Critical
            probabilities:
              '0': 0.0003348349100603869
              '1': 3.529133987660637e-05
              '2': 0.0015006266723396524
              '3': 0.9981292470777234
            confidence: 0.9894200002646713
        usage:
          input_tokens: 267
          output_tokens: 4
    DecisionModelUsage:
      type: object
      description: Token usage for the completed evaluation.
      properties:
        input_tokens:
          type: integer
          minimum: 0
          description: Input tokens processed, including shared-context preparation and question evaluation. This can exceed the token count of the unique input text.
        output_tokens:
          type: integer
          minimum: 0
          description: Output tokens used for the evaluation, including shared-context preparation.
      required:
      - input_tokens
      - output_tokens
      additionalProperties: false
    DecisionModelAnswer:
      description: An answer whose type matches its question.
      oneOf:
      - $ref: '#/components/schemas/DecisionModelChoiceAnswer'
      - $ref: '#/components/schemas/DecisionModelNoulAnswer'
      - $ref: '#/components/schemas/DecisionModelScoreAnswer'
      discriminator:
        propertyName: type
        mapping:
          choice: '#/components/schemas/DecisionModelChoiceAnswer'
          noul: '#/components/schemas/DecisionModelNoulAnswer'
          score: '#/components/schemas/DecisionModelScoreAnswer'
    DecisionModelConfidence:
      type: number
      description: 'Normalized entropy confidence: 1 - H(p) / ln(N), where H(p) = -sum(p * ln(p)) and N is the number of options. Zero indicates a uniform distribution; one indicates concentration on one option. This is neither the winning probability nor calibrated correctness.'
      minimum: 0
      maximum: 1
    DecisionModelQuestion:
      description: A choice, yes/no, or ordered-score question.
      oneOf:
      - $ref: '#/components/schemas/DecisionModelChoiceQuestion'
      - $ref: '#/components/schemas/DecisionModelNoulQuestion'
      - $ref: '#/components/schemas/DecisionModelScoreQuestion'
      discriminator:
        propertyName: type
        mapping:
          choice: '#/components/schemas/DecisionModelChoiceQuestion'
          noul: '#/components/schemas/DecisionModelNoulQuestion'
          score: '#/components/schemas/DecisionModelScoreQuestion'
    DecisionModelChoiceQuestion:
      type: object
      description: Select one of the supplied options.
      properties:
        type:
          type: string
          description: Question type.
          enum:
          - choice
        instructions:
          $ref: '#/components/schemas/DecisionModelContent'
          description: Required instructions describing what to decide about the shared state.
        criteria:
          type: object
          description: Between 2 and 64 option keys mapped to description strings or null. A null description uses the option key as its text.
          minProperties: 2
          maxProperties: 64
          additionalProperties:
            type:
            - string
            - 'null'
      required:
      - type
      - instructions
      - criteria
      additionalProperties: false
      example:
        type: choice
        instructions: Choose the team that should handle this incident.
        criteria:
          billing: Payments and refunds
          technical_support: Service faults and technical problems
          sales: New purchases
    DecisionModelNoulAnswer:
      type: object
      description: A yes/no score with no separate confidence or probabilities fields.
      properties:
        type:
          type: string
          description: Answer type.
          enum:
          - noul
        noul:
          type: number
          description: Score of the positive outcome. Values near 1 favor yes; values near 0 favor no. This is a number, not a Boolean, and is not calibrated correctness.
          minimum: 0
          maximum: 1
      required:
      - type
      - noul
      additionalProperties: false
      example:
        type: noul
        noul: 0.9991959141264766
    DecisionModelScoreAnswer:
      type: object
      description: An expected rating over the ordered criteria.
      properties:
        type:
          type: string
          description: Answer type.
          enum:
          - score
        score:
          type: number
          description: 'Expected zero-based criterion index: sum(index * probability). Ranges from 0 to N-1 for N criteria; fractional values are valid.'
          minimum: 0
          maximum: 63
        legend:
          type: object
          description: Criterion descriptions keyed by stringified zero-based indices, such as "0", "1", and "2".
          minProperties: 2
          maxProperties: 64
          additionalProperties:
            type: string
        probabilities:
          $ref: '#/components/schemas/DecisionModelProbabilities'
          description: Relative scores keyed by the same stringified indices as legend.
        confidence:
          $ref: '#/components/schemas/DecisionModelConfidence'
      required:
      - type
      - score
      - legend
      - probabilities
      - confidence
      additionalProperties: false
      example:
        type: score
        score: 2.9974242859177265
        legend:
          '0': Low
          '1': Normal
          '2': High
          '3': Critical
        probabilities:
          '0': 0.0003348349100603869
          '1': 3.529133987660637e-05
          '2': 0.0015006266723396524
          '3': 0.9981292470777234
        confidence: 0.9894200002646713
    DecisionModelRequest:
      type: object
      description: Decision Models beta request. Choose a public model alias; omitted model defaults to telnyx/decision-flash. Telnyx manages the underlying models behind these aliases.
      properties:
        model:
          type: string
          enum:
          - telnyx/decision-flash
          - telnyx/decision-pro
          default: telnyx/decision-flash
          description: Public model alias. telnyx/decision-flash offers the lowest cost and latency; telnyx/decision-pro supports decisions that require long context, including inputs beyond Jev’s 32k per-decision limit. Applies to every question in the request. Other values are rejected.
          example: telnyx/decision-flash
        state:
          $ref: '#/components/schemas/DecisionModelContent'
          description: Shared context evaluated by every question.
          example: Our production calls are failing. Every customer is affected.
        questions:
          type: object
          description: Between 1 and 64 named questions. Each key identifies the corresponding answer.
          minProperties: 1
          maxProperties: 64
          additionalProperties:
            $ref: '#/components/schemas/DecisionModelQuestion'
      required:
      - state
      - questions
      additionalProperties: false
      example:
        model: telnyx/decision-flash
        state: Our production calls are failing. Every customer is affected.
        questions:
          team:
            type: choice
            instructions: Choose the team that should handle this incident.
            criteria:
              billing: Payments and refunds
              technical_support: Service faults and technical problems
              sales: New purchases
          production_incident:
            type: noul
            instructions: Does the message describe an active production incident?
          urgency:
            type: score
            instructions: Rate operational urgency.
            criteria:
            - Low
            - Normal
            - High
            - Critical
    DecisionModelError:
      type: object
      description: A decision model service error.
      properties:
        error:
          type: object
          description: Error details.
          properties:
            message:
              type: string
              description: Human-readable explanation of the failure.
          required:
          - message
          additionalProperties: false
      required:
      - error
      additionalProperties: false
    DecisionModelNoulCriteria:
      type: object
      description: Optional descriptions for the positive and negative outcomes. Descriptions must be strings.
      properties:
        'true':
          type: string
          description: Description of the positive outcome.
          default: 'Yes'
        'false':
          type: string
          description: Description of the negative outcome.
          default: 'No'
      required: []
      additionalProperties: false
      default:
        'true': 'Yes'
        'false': 'No'
    DecisionModelNoulQuestion:
      type: object
      description: Evaluate a yes/no question. Omit criteria to use Yes and No descriptions.
      properties:
        type:
          type: string
          description: Question type.
          enum:
          - noul
        instructions:
          $ref: '#/components/schemas/DecisionModelContent'
          description: Required instructions describing what to decide about the shared state.
        criteria:
          $ref: '#/components/schemas/DecisionModelNoulCriteria'
      required:
      - type
      - instructions
      additionalProperties: false
      example:
        type: noul
        instructions: Does the message describe an active production incident?
    DecisionModelChoiceAnswer:
      type: object
      description: A selected option and the distribution across all supplied option keys.
      properties:
        type:
          type: string
          description: Answer type.
          enum:
          - choice
        choice:
          type: string
          description: The option key with the highest relative score. Ties favor the first option in request order.
        probabilities:
          $ref: '#/components/schemas/DecisionModelProbabilities'
        confidence:
          $ref: '#/components/schemas/DecisionModelConfidence'
      required:
      - type
      - choice
      - probabilities
      - confidence
      additionalProperties: false
      example:
        type: choice
        choice: technical_support
        probabilities:
          billing: 0.0024719786572585446
          technical_support: 0.9972674768333701
          sales: 0.00026054450937119613
        confidence: 0.9820522416354122
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: 'Telnyx API key supplied as `Authorization: Bearer <token>`. In production, auth may be validated by the API gateway and forwarded via Telnyx auth headers.'
    Payment:
      type: apiKey
      in: header
      name: Authorization
      description: 'Machine Payment Protocol credential used on paid retries, sent as `Authorization: Payment ...`. Obtained by paying a challenge returned in the `WWW-Authenticate` header of a 402 response. This is not a Telnyx API key; initial challenge requests use standard bearer authentication instead.'
    agent-memory_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key
    bearerAuth:
      type: http
      scheme: bearer
    branded-calling_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Generate one at https://portal.telnyx.com/#/app/api-keys.
    collections_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Collections and results are automatically scoped to the authenticated user's organization.
    number-reputation_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Generate one at https://portal.telnyx.com/#/app/api-keys.
    oauthClientAuth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
        authorizationCode:
          authorizationUrl: https://api.telnyx.com/v2/oauth/authorize
          tokenUrl: https://api.telnyx.com/v2/oauth/token
          refreshUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
      description: OAuth 2.0 authentication for Telnyx API and MCP integrations
    outbound-voice-profiles_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    pronunciation-dicts_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API v2 key. Obtain from https://portal.telnyx.com
    rcs-registration_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
    stored-payment-transactions_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    transcriptions-search_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Results are automatically scoped to the authenticated user's organization.
    web-search_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key
x-service-info:
  categories:
  - communication
  - developer-tools
  docs:
    apiReference: https://developers.telnyx.com
    homepage: https://telnyx.com
    llms: https://telnyx.com/llms.txt