Forethought Conversations API

openapi: 3.1.0
info:
  title: Forethought Solve Conversations 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.
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'
components:
  schemas:
    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
    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.
    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.
  responses:
    RateLimited:
      description: Request rate limit exceeded.
    Unauthorized:
      description: Missing or invalid bearer token.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Solve API token