openapi: 3.1.0
info:
  title: Forethought Triage API
  description: |
    The Forethought Triage API classifies customer-support tickets and predicts
    the most likely category, sub-category, language, sentiment, or other label
    your Triage model is trained on. Forethought's Implementation Engineering
    team trains and deploys the model and issues a bearer token. Submit the
    ticket subject (`text_a`) and body (`text_b`) and the API returns ranked
    predictions with confidence scores.
  version: '2025-11-01'
  contact:
    name: Forethought Support
    url: https://support.forethought.ai

servers:
  - url: https://api.forethought.ai
    description: Production Server

security:
  - BearerAuth: []

tags:
  - name: Predictions
    description: Predict labels for customer-support tickets.

paths:
  /api/predict:
    post:
      summary: Predict Ticket Triage Labels
      description: |
        Submit a ticket subject and body and receive ranked predictions from a
        Forethought Triage model. Each prediction includes a `prediction_value`
        (the label) and `prediction_confidence` (0.0 to 1.0). Use the top
        prediction to route tickets, populate ticket fields, or trigger
        downstream workflows in Zendesk, Salesforce, or other helpdesks.
      operationId: predictTriage
      tags:
        - Predictions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PredictRequest'
      responses:
        '200':
          description: Predictions returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PredictResponse'
        '401':
          description: Missing or invalid bearer token.
        '404':
          description: Triage model not found.
        '429':
          description: Request rate limit exceeded.

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Triage API token
  schemas:
    PredictRequest:
      type: object
      required:
        - model_name
        - text_a
      properties:
        model_name:
          type: string
          description: The Triage model identifier provided by Forethought.
        text_a:
          type: string
          description: Ticket subject or short title.
        text_b:
          type: string
          description: Ticket body or extended description.
    PredictResponse:
      type: object
      properties:
        model_name:
          type: string
        prediction_confidence:
          type: number
          format: float
          minimum: 0
          maximum: 1
        top_predictions:
          type: array
          items:
            $ref: '#/components/schemas/Prediction'
    Prediction:
      type: object
      properties:
        prediction_value:
          type: string
          description: The predicted label.
        prediction_confidence:
          type: number
          format: float
          minimum: 0
          maximum: 1