Arcee AI Chat API

openapi: 3.1.0
info:
  title: AFM Access Profiles Chat API
  version: 0.1.0
tags:
- name: Chat
paths:
  /app/v1/chat:
    post:
      tags:
      - Chat
      summary: Create Chat
      description: Create a new chat session.
      operationId: create_chat_app_v1_chat_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCreate'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /app/v1/chat/{id}:
    get:
      tags:
      - Chat
      summary: Get Chat
      description: Get a specific chat session by ID.
      operationId: get_chat_app_v1_chat__id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - Chat
      summary: Update Chat
      description: Update a chat session.
      operationId: update_chat_app_v1_chat__id__put
      security:
      - HTTPBearer: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Chat
      summary: Delete Chat
      description: Delete a chat session.
      operationId: delete_chat_app_v1_chat__id__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /app/v1/chats:
    get:
      tags:
      - Chat
      summary: Get User Chats
      description: 'Get paginated chat sessions for the current user.

        Optionally filter by search term in title.'
      operationId: get_user_chats_app_v1_chats_get
      security:
      - HTTPBearer: []
      parameters:
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Offset
      - name: search
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Search
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /app/v1/chat/{session_id}/history:
    get:
      tags:
      - Chat
      summary: Get Chat History
      description: Get conversation history for a chat session.
      operationId: get_chat_history_app_v1_chat__session_id__history_get
      security:
      - HTTPBearer: []
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Session Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatHistoryResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /app/v1/chat/{session_id}/messages:
    get:
      tags:
      - Chat
      summary: Get Session Messages
      description: Get messages for a specific chat session.
      operationId: get_session_messages_app_v1_chat__session_id__messages_get
      security:
      - HTTPBearer: []
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Session Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ChatMessageResponse'
                title: Response Get Session Messages App V1 Chat  Session Id  Messages Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /app/v1/chat/{session_id}/message/{message_id}/meta:
    patch:
      tags:
      - Chat
      summary: Update Message Meta
      description: 'Update the meta field of a message (merges with existing meta).


        The session_id is required to verify user access and ensure the message

        belongs to the specified session. Returns 404 if the session is not accessible

        or the message doesn''t exist within that session.'
      operationId: update_message_meta_app_v1_chat__session_id__message__message_id__meta_patch
      security:
      - HTTPBearer: []
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Session Id
      - name: message_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Message Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageMetaUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatMessageResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /app/v1/chat/{session_id}/message/{message_id}:
    delete:
      tags:
      - Chat
      summary: Delete Message
      description: 'Delete a user or assistant message and its corresponding pair.


        This endpoint deletes the specified user or assistant message along with its paired

        message (the next assistant message if a user message is provided, or the previous user

        message if an assistant message is provided). Any file attachments stored in S3 are also deleted.


        - Only user and assistant messages can be deleted (not system messages)

        - The corresponding paired message is automatically deleted

        - S3 file attachments from both messages are cleaned up


        Returns the IDs of all deleted messages.'
      operationId: delete_message_app_v1_chat__session_id__message__message_id__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Session Id
      - name: message_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Message Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteMessageResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /app/v1/chat/flag-response:
    post:
      tags:
      - Chat
      summary: Flag Message
      description: 'Flag a message for review.


        This endpoint allows users to flag a specific message within a chat session for review. The flagged message

        is associated with the user''s organization and can be reviewed by administrators.


        Returns a success message upon successful flagging.'
      operationId: flag_message_app_v1_chat_flag_response_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FlagResponseRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /app/v1/prompts:
    post:
      tags:
      - Chat
      summary: Create Prompt
      description: Create a new prompt.
      operationId: create_prompt_app_v1_prompts_post
      security:
      - HTTPBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PromptCreate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromptResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Chat
      summary: Get User Prompts
      description: Get all prompts for the current user.
      operationId: get_user_prompts_app_v1_prompts_get
      security:
      - HTTPBearer: []
      parameters:
      - name: skip
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Skip
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PromptResponse'
                title: Response Get User Prompts App V1 Prompts Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /app/v1/prompts/{prompt_id}:
    get:
      tags:
      - Chat
      summary: Get Prompt
      description: Get a specific prompt by ID.
      operationId: get_prompt_app_v1_prompts__prompt_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: prompt_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Prompt Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromptResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - Chat
      summary: Update Prompt
      description: Update an existing prompt.
      operationId: update_prompt_app_v1_prompts__prompt_id__put
      security:
      - HTTPBearer: []
      parameters:
      - name: prompt_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Prompt Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PromptUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromptResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Chat
      summary: Delete Prompt
      description: Delete a prompt.
      operationId: delete_prompt_app_v1_prompts__prompt_id__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: prompt_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Prompt Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /app/v1/prompts/set_active:
    post:
      tags:
      - Chat
      summary: Set Active Prompt
      description: Set a prompt as the active prompt for the user.
      operationId: set_active_prompt_app_v1_prompts_set_active_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PromptSetActiveRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /app/v1/chat-models:
    get:
      tags:
      - Chat
      summary: Get Chat Models
      description: 'Get all models and tools for the chat interface.

        Returns models with their available tools and all available tools metadata.'
      operationId: get_chat_models_app_v1_chat_models_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatModelsResponse'
      security:
      - HTTPBearer: []
components:
  schemas:
    ChatToolResponse:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
        icon:
          type: string
          title: Icon
        enabled:
          type: boolean
          title: Enabled
          default: true
        activeStateLabel:
          anyOf:
          - type: string
          - type: 'null'
          title: Activestatelabel
      type: object
      required:
      - id
      - name
      - description
      - icon
      title: ChatToolResponse
      description: Tool response for chat models endpoint.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    ChatMessageResponse:
      properties:
        content:
          type: string
          maxLength: 1000000
          title: Content
          description: Message content (max 1,000,000 characters, supports base64 images)
        reasoning_content:
          anyOf:
          - type: string
          - type: 'null'
          title: Reasoning Content
          description: Reasoning trace for the assistant message (separate from content).
        tool_calls:
          anyOf:
          - items:
              additionalProperties: true
              type: object
            type: array
          - type: 'null'
          title: Tool Calls
          description: 'Server-side tool execution results: list of {tool_call_id, name, arguments, result|error, duration_ms, agent_iteration, content_offset_at_call, reasoning_offset_at_call} entries. The three trailing fields are character indices into `content` / `reasoning_content` at the moment the tool was invoked; the frontend uses them on reload to splice tool segments back into the natural interleaved order. NULL on rows persisted before the offset columns were added; consumers should fall back to clumped rendering in that case. Sourced from the `tool_executions` table via the `tool_calls` @property on the SQLAlchemy ChatMessage. Callers must `selectinload` the `tool_executions` relationship before serializing; otherwise the field will be None even when executions exist.'
        role:
          $ref: '#/components/schemas/MessageRole'
        meta:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Meta
        id:
          type: string
          format: uuid
          title: Id
        session_id:
          type: string
          format: uuid
          title: Session Id
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - content
      - role
      - id
      - session_id
      - created_at
      title: ChatMessageResponse
      description: Chat message with database fields.
    ChatModelResponse:
      properties:
        id:
          type: string
          title: Id
        display_name:
          type: string
          title: Display Name
        model_id:
          type: string
          title: Model Id
        base_model_name:
          type: string
          title: Base Model Name
        model_icon:
          anyOf:
          - type: string
          - type: 'null'
          title: Model Icon
        provider_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Provider Name
        availableTools:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Availabletools
        is_default:
          type: boolean
          title: Is Default
          default: false
        is_healthy:
          type: boolean
          title: Is Healthy
          default: true
        default_params:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Default Params
      type: object
      required:
      - id
      - display_name
      - model_id
      - base_model_name
      title: ChatModelResponse
      description: Model response for chat models endpoint.
    PromptResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        prompt:
          type: string
          title: Prompt
        user_org_profile_id:
          type: string
          format: uuid
          title: User Org Profile Id
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Updated At
        is_active:
          type: boolean
          title: Is Active
      type: object
      required:
      - id
      - prompt
      - user_org_profile_id
      - created_at
      - is_active
      title: PromptResponse
      description: Prompt response with database fields.
    ChatListResponse:
      properties:
        total:
          type: integer
          title: Total
        offset:
          type: integer
          title: Offset
        limit:
          type: integer
          title: Limit
        content:
          items:
            $ref: '#/components/schemas/ChatResponse'
          type: array
          title: Content
      type: object
      required:
      - total
      - offset
      - limit
      - content
      title: ChatListResponse
      description: Paginated chat list response.
    ChatCreate:
      properties:
        title:
          anyOf:
          - type: string
            maxLength: 600
          - type: 'null'
          title: Title
          description: Chat title (max 600 characters)
        meta:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Meta
        messages:
          anyOf:
          - items:
              additionalProperties: true
              type: object
            type: array
          - type: 'null'
          title: Messages
        initialMessage:
          anyOf:
          - type: string
            maxLength: 1000000
          - type: 'null'
          title: Initialmessage
          description: Initial message (max 1,000,000 characters)
        user_org_profile_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: User Org Profile Id
      type: object
      title: ChatCreate
      description: Model for creating a new chat.
    PromptSetActiveRequest:
      properties:
        prompt_id:
          type: string
          format: uuid
          title: Prompt Id
      type: object
      required:
      - prompt_id
      title: PromptSetActiveRequest
      description: Set a prompt as the active prompt for the user.
    DeleteMessageResponse:
      properties:
        deleted_message_ids:
          items:
            type: string
            format: uuid
          type: array
          title: Deleted Message Ids
        success:
          type: boolean
          title: Success
      type: object
      required:
      - deleted_message_ids
      - success
      title: DeleteMessageResponse
      description: Response model for deleting a message and its corresponding response.
    PromptCreate:
      properties:
        prompt:
          type: string
          title: Prompt
      type: object
      required:
      - prompt
      title: PromptCreate
      description: Model for creating a new prompt.
    FlagResponseRequest:
      properties:
        message_id:
          type: string
          format: uuid
          title: Message Id
        session_id:
          type: string
          format: uuid
          title: Session Id
        reason:
          type: string
          title: Reason
        additional_comments:
          anyOf:
          - type: string
          - type: 'null'
          title: Additional Comments
        meta:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Meta
      type: object
      required:
      - message_id
      - session_id
      - reason
      title: FlagResponseRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ChatHistoryResponse:
      properties:
        session_id:
          type: string
          format: uuid
          title: Session Id
        messages:
          items:
            $ref: '#/components/schemas/ChatMessageResponse'
          type: array
          title: Messages
      type: object
      required:
      - session_id
      - messages
      title: ChatHistoryResponse
    MessageMetaUpdate:
      properties:
        meta:
          additionalProperties: true
          type: object
          title: Meta
      type: object
      required:
      - meta
      title: MessageMetaUpdate
      description: Model for updating message meta.
    ChatModelsResponse:
      properties:
        models:
          items:
            $ref: '#/components/schemas/ChatModelResponse'
          type: array
          title: Models
        tools:
          items:
            $ref: '#/components/schemas/ChatToolResponse'
          type: array
          title: Tools
      type: object
      required:
      - models
      - tools
      title: ChatModelsResponse
      description: Response model for chat models and tools endpoint.
    MessageRole:
      type: string
      enum:
      - user
      - assistant
      - system
      title: MessageRole
    PromptUpdate:
      properties:
        prompt:
          type: string
          title: Prompt
      type: object
      required:
      - prompt
      title: PromptUpdate
      description: Update an existing prompt.
    ChatResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        user_org_profile_id:
          type: string
          format: uuid
          title: User Org Profile Id
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        meta:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Meta
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Updated At
      type: object
      required:
      - id
      - user_org_profile_id
      - created_at
      title: ChatResponse
      description: Chat response with database fields.
    ChatUpdate:
      properties:
        title:
          anyOf:
          - type: string
            maxLength: 600
          - type: 'null'
          title: Title
          description: Chat title (max 600 characters)
        meta:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Meta
      type: object
      title: ChatUpdate
      description: Update a chat session with optional fields.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer