openapi: 3.1.0
info:
  title: Assembled Assist API
  description: |
    The AI surface of Assembled.

    Submit chat responses generated by AI Agents, manage the knowledge
    articles AI Agents draw from, retrieve conversation histories and
    handoff payloads, and (beta) post AI replies. Powers autonomous
    resolution across chat, email, SMS, and voice plus smart handoffs to
    human agents.
  version: '2026-05-24'
  contact:
    name: Assembled Support
    url: https://support.assembled.com
servers:
  - url: https://api.assembledhq.com
    description: Production Server
security:
  - BasicAuth: []
tags:
  - name: Assist Responses
  - name: Assist Articles
  - name: Assist Conversations
  - name: Assist Replies
paths:
  /v0/assist/responses:
    post:
      summary: Assembled Submit Assist Response
      description: Submit a chat response generated by an Assembled AI Agent.
      operationId: submitAssistResponse
      tags: [Assist Responses]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/AssistResponseInput' }
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AssistResponse' }
  /v0/assist/responses/handoff:
    get:
      summary: Assembled Get Assist Response Handoff
      description: Retrieve handoff payloads for responses that escalated to a human agent.
      operationId: getAssistResponseHandoff
      tags: [Assist Responses]
      parameters:
        - in: query
          name: conversation_id
          schema: { type: string }
        - in: query
          name: since
          schema: { type: string, format: date-time }
      responses:
        '200':
          description: Handoff payloads
          content:
            application/json:
              schema:
                type: object
                properties:
                  handoffs:
                    type: array
                    items: { $ref: '#/components/schemas/AssistHandoff' }
  /v0/assist/conversations:
    get:
      summary: Assembled List Assist Conversations
      description: List AI-assisted conversations.
      operationId: listAssistConversations
      tags: [Assist Conversations]
      parameters:
        - in: query
          name: start_time
          schema: { type: string, format: date-time }
        - in: query
          name: end_time
          schema: { type: string, format: date-time }
        - in: query
          name: status
          schema: { type: string }
      responses:
        '200':
          description: Conversations
          content:
            application/json:
              schema:
                type: object
                properties:
                  conversations:
                    type: array
                    items: { $ref: '#/components/schemas/AssistConversation' }
  /v0/assist/conversations/{id}/handoff:
    get:
      summary: Assembled Get Assist Conversation Handoff
      description: Retrieve the handoff payload for a single AI-assisted conversation.
      operationId: getAssistConversationHandoff
      tags: [Assist Conversations]
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Handoff payload
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AssistHandoff' }
  /v0/assist/articles:
    post:
      summary: Assembled Create Assist Article
      description: Create a knowledge article that AI Agents can reference.
      operationId: createAssistArticle
      tags: [Assist Articles]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/AssistArticleInput' }
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AssistArticle' }
  /v0/assist/articles/{id}:
    put:
      summary: Assembled Update Assist Article
      operationId: updateAssistArticle
      tags: [Assist Articles]
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/AssistArticleInput' }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AssistArticle' }
    delete:
      summary: Assembled Delete Assist Article
      operationId: deleteAssistArticle
      tags: [Assist Articles]
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string }
      responses:
        '204':
          description: Deleted
  /v0/assist/replies:
    post:
      summary: Assembled Submit Assist Reply (Beta)
      description: Beta endpoint for posting AI-generated replies directly. Subject to change.
      operationId: submitAssistReply
      tags: [Assist Replies]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                conversation_id: { type: string }
                channel: { type: string }
                body: { type: string }
                confidence: { type: number }
      responses:
        '202':
          description: Accepted
components:
  securitySchemes:
    BasicAuth: { type: http, scheme: basic }
  schemas:
    AssistResponseInput:
      type: object
      required: [conversation_id, body]
      properties:
        conversation_id: { type: string }
        channel: { type: string, enum: [chat, email, sms, voice] }
        body: { type: string }
        confidence: { type: number }
        model: { type: string }
        cited_article_ids:
          type: array
          items: { type: string }
        metadata:
          type: object
          additionalProperties: true
    AssistResponse:
      allOf:
        - $ref: '#/components/schemas/AssistResponseInput'
        - type: object
          properties:
            id: { type: string }
            created_at: { type: string, format: date-time }
    AssistConversation:
      type: object
      properties:
        id: { type: string }
        channel: { type: string }
        status: { type: string, example: resolved }
        started_at: { type: string, format: date-time }
        ended_at: { type: string, format: date-time, nullable: true }
        resolved_by: { type: string, enum: [ai, human, mixed] }
        customer_id: { type: string }
        handoff_id: { type: string, nullable: true }
    AssistHandoff:
      type: object
      properties:
        id: { type: string }
        conversation_id: { type: string }
        handed_off_at: { type: string, format: date-time }
        reason: { type: string }
        summary: { type: string }
        transcript:
          type: array
          items:
            type: object
            properties:
              role: { type: string, enum: [customer, ai, human] }
              content: { type: string }
              timestamp: { type: string, format: date-time }
    AssistArticle:
      type: object
      properties:
        id: { type: string }
        title: { type: string }
        body: { type: string }
        tags:
          type: array
          items: { type: string }
        source_url: { type: string }
        published: { type: boolean }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
    AssistArticleInput:
      type: object
      required: [title, body]
      properties:
        title: { type: string }
        body: { type: string }
        tags:
          type: array
          items: { type: string }
        source_url: { type: string }
        published: { type: boolean }