openapi: 3.0.1
info:
  title: Mendable Chat API
  description: REST API for the Mendable AI answers and enterprise search platform. Create conversations, ask grounded questions over ingested documentation and knowledge sources (with Server-Sent Events streaming), ingest and manage data sources, and rate answers. All endpoints authenticate with a Mendable api_key passed in the JSON request body; a Bearer token is also accepted.
  termsOfService: https://www.mendable.ai/terms
  contact:
    name: Mendable Support
    url: https://docs.mendable.ai
    email: help@firecrawl.com
  version: '1.0'
servers:
- url: https://api.mendable.ai/v1
  description: Mendable production API
security:
- apiKeyBody: []
- bearerAuth: []
tags:
- name: Chat
  description: Ask grounded questions over ingested content.
paths:
  /mendableChat:
    post:
      operationId: mendableChat
      tags:
      - Chat
      summary: Ask a question over ingested content
      description: Sends a question to the Mendable AI assistant grounded in the project's ingested data. By default the response streams as Server-Sent Events; set shouldStream to false to receive a single JSON response with the answer, sources, and message_id.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MendableChatRequest'
      responses:
        '200':
          description: Chat answer. When shouldStream is true (default) the body is a Server-Sent Events stream of source, text, and message_id chunks; when false the body is a single JSON object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MendableChatResponse'
            text/event-stream:
              schema:
                type: string
                description: SSE stream. Includes a <|source|> chunk with the sources array, text chunks forming the answer, and a <|message_id|> chunk with the message identifier.
        '400':
          description: Missing or invalid api_key, or missing question.
components:
  schemas:
    Source:
      type: object
      properties:
        id:
          type: string
        content:
          type: string
        link:
          type: string
        relevance_score:
          type: number
    HistoryItem:
      type: object
      properties:
        prompt:
          type: string
        response:
          type: string
        sources:
          type: array
          items:
            $ref: '#/components/schemas/Source'
    MendableChatResponse:
      type: object
      description: Non-streaming chat response (shouldStream=false).
      properties:
        answer:
          type: object
          properties:
            text:
              type: string
              description: The AI-generated answer.
        message_id:
          type: number
          description: Identifier of the answer message.
        sources:
          type: array
          items:
            $ref: '#/components/schemas/Source'
        tools_used:
          type: array
          items:
            type: object
            additionalProperties: true
    MendableChatRequest:
      type: object
      required:
      - api_key
      - question
      - history
      properties:
        api_key:
          type: string
          description: Your Mendable API key.
        question:
          type: string
          description: The user's question.
        history:
          type: array
          description: Prior conversation turns, each with prompt and response strings and optional source objects.
          items:
            $ref: '#/components/schemas/HistoryItem'
        conversation_id:
          type: number
          description: Conversation identifier returned from /newConversation.
        temperature:
          type: number
          format: float
          description: Controls randomness (0.0-1.0).
        additional_context:
          type: string
          description: Extra context appended to the prompt.
        relevance_threshold:
          type: number
          description: Filters out sources scoring below this threshold (0-1).
        where:
          type: object
          additionalProperties: true
          description: Metadata-based source filtering.
        retriever_options:
          type: object
          description: Retrieval configuration.
          properties:
            num_chunks:
              type: integer
              description: Number of chunks to retrieve.
        shouldStream:
          type: boolean
          default: true
          description: Set to false to receive a single JSON response instead of an SSE stream.
        tracking:
          type: object
          additionalProperties: true
          description: Analytics metadata such as roleInfo for user role tracking.
  securitySchemes:
    apiKeyBody:
      type: apiKey
      in: query
      name: api_key
      description: Mendable api_key. Sent as the api_key field inside the JSON request body for every endpoint (modeled here as apiKey for tooling).
    bearerAuth:
      type: http
      scheme: bearer
      description: Mendable api_key supplied as a Bearer token in the Authorization header.