openapi: 3.1.0
info:
  title: Forethought Solve API
  description: |
    The Forethought Solve API is a headless interface to the Solve generative AI
    customer support agent. Embed Solve into any application by starting a
    conversation with a free-form customer query, then continuing the
    conversation with additional turns or context variables. The metadata
    endpoint returns the workspace's configured context variables so clients
    can pass the correct values when triggering Autoflows and workflows.

    The Solve API is part of Forethought's Headless channel and is available on
    the Enterprise plan. SupportGPT, Forethought's generative AI engine, powers
    response generation, Autoflows, knowledge-base gap detection, and
    article-creation behind the API.
  version: '2025-11-01'
  contact:
    name: Forethought Support
    url: https://support.forethought.ai
  x-logo:
    url: https://forethought.ai/favicon.ico

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

security:
  - BearerAuth: []

tags:
  - name: Conversations
    description: Start and continue Solve conversations.
  - name: Metadata
    description: Inspect workspace-level Solve configuration.

paths:
  /solve/api/v1/conversation:
    post:
      summary: Start A Solve Conversation
      description: |
        Start a new Solve conversation with a free-form customer query.
        Returns a `conversation_id` that subsequent turns must reference and the
        first assistant response. Optionally accepts a map of context variables
        whose IDs are discoverable via the `/metadata` endpoint.
      operationId: startConversation
      tags:
        - Conversations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartConversationRequest'
      responses:
        '200':
          description: Conversation started successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /solve/api/v1/conversation/{conversation_id}:
    put:
      summary: Continue A Solve Conversation
      description: |
        Continue an existing Solve conversation by sending an additional query
        and/or updated context variables. The Solve agent returns the next
        assistant response, surface workflow state, and any escalation
        instructions.
      operationId: continueConversation
      tags:
        - Conversations
      parameters:
        - name: conversation_id
          in: path
          required: true
          schema:
            type: string
          description: The conversation_id returned by the initial start call.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContinueConversationRequest'
      responses:
        '200':
          description: Conversation continued successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Conversation not found.
        '429':
          $ref: '#/components/responses/RateLimited'
  /solve/api/v1/metadata:
    get:
      summary: List Solve Workspace Metadata
      description: |
        Return the workspace's Solve configuration including the list of
        defined context variables (both predefined and customer-defined) with
        ID, display name, and type. Use these IDs when passing context to the
        conversation endpoints.
      operationId: getMetadata
      tags:
        - Metadata
      responses:
        '200':
          description: Metadata returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetadataResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Solve API token
  responses:
    Unauthorized:
      description: Missing or invalid bearer token.
    RateLimited:
      description: Request rate limit exceeded.
  schemas:
    StartConversationRequest:
      type: object
      required:
        - query
      properties:
        query:
          type: string
          description: The customer's free-form query.
        context_variables:
          type: object
          additionalProperties: true
          description: Map of context_variable_id to value.
        channel:
          type: string
          description: Origin channel (chat, email, voice, slack, headless).
        user_id:
          type: string
          description: Stable identifier for the end user.
    ContinueConversationRequest:
      type: object
      properties:
        query:
          type: string
          description: The customer's next free-form query.
        context_variables:
          type: object
          additionalProperties: true
          description: Updated context variables for the conversation.
    ConversationResponse:
      type: object
      properties:
        conversation_id:
          type: string
        response:
          type: string
          description: The Solve agent response text.
        is_solved:
          type: boolean
        should_escalate:
          type: boolean
        workflow_id:
          type: string
        intent:
          type: string
    MetadataResponse:
      type: object
      properties:
        context_variables:
          type: array
          items:
            $ref: '#/components/schemas/ContextVariable'
    ContextVariable:
      type: object
      properties:
        context_variable_id:
          type: string
        display_name:
          type: string
        is_predefined:
          type: boolean
        context_variable_type:
          type: string
          enum: [string, number, boolean, list, object]