Aleph Alpha Conversations API

openapi: 3.2.0
info:
  title: Stateful Responses Conversations API
  version: 0.4.23
  description: Create, retrieve, update, delete, and list conversations.
servers:
- url: '{host}'
  variables:
    host:
      default: https://api.pharia.example.com
tags:
- name: Conversations
  description: Create, retrieve, update, delete, and list conversations.
paths:
  /v1/conversations:
    post:
      tags:
      - Conversations
      summary: Create Conversation Endpoint
      description: Create a new conversation.
      operationId: create_conversation_endpoint_v1_conversations_post
      security:
      - HTTPBearer: []
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/CreateConversationRequest'
              - type: 'null'
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationResponse'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not Found
        '422':
          description: Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically.
        '425':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Too Early
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal Server Error
        '501':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not Implemented
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad Gateway
    get:
      tags:
      - Conversations
      summary: List Conversations Endpoint
      description: 'List conversations for the authenticated user.


        Admin access: when the caller is an admin, ALL users'' conversations are

        returned (titles, metadata, timestamps). This is a privileged operation.'
      operationId: list_conversations_endpoint_v1_conversations_get
      security:
      - HTTPBearer: []
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 20
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Offset
      - name: order
        in: query
        required: false
        schema:
          type: string
          default: desc
          title: Order
      - name: metadata.application
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Metadata.Application
      - name: include_deleted
        in: query
        required: false
        schema:
          type: boolean
          description: Include soft-deleted conversations. Admin-only; returns 403 for non-admin callers.
          default: false
          title: Include Deleted
        description: Include soft-deleted conversations. Admin-only; returns 403 for non-admin callers.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationListResponse'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not Found
        '422':
          description: Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically.
        '425':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Too Early
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal Server Error
        '501':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not Implemented
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad Gateway
  /v1/conversations/{conversation_id}:
    get:
      tags:
      - Conversations
      summary: Get Conversation Endpoint
      description: 'Retrieve a conversation by ID.


        Admin access: when the caller is an admin, ownership checks are bypassed,

        allowing cross-user retrieval.'
      operationId: get_conversation_endpoint_v1_conversations__conversation_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: conversation_id
        in: path
        required: true
        schema:
          type: string
          title: Conversation Id
      - name: include_deleted
        in: query
        required: false
        schema:
          type: boolean
          description: Include soft-deleted conversations. Admin-only; returns 403 for non-admin callers.
          default: false
          title: Include Deleted
        description: Include soft-deleted conversations. Admin-only; returns 403 for non-admin callers.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationResponse'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not Found
        '422':
          description: Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically.
        '425':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Too Early
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal Server Error
        '501':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not Implemented
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad Gateway
    post:
      tags:
      - Conversations
      summary: Update Conversation Endpoint
      description: 'Update conversation metadata.


        Admin access: when the caller is an admin, ownership checks are bypassed,

        allowing cross-user metadata updates.'
      operationId: update_conversation_endpoint_v1_conversations__conversation_id__post
      security:
      - HTTPBearer: []
      parameters:
      - name: conversation_id
        in: path
        required: true
        schema:
          type: string
          title: Conversation Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateConversationRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationResponse'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not Found
        '422':
          description: Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically.
        '425':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Too Early
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal Server Error
        '501':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not Implemented
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad Gateway
    delete:
      tags:
      - Conversations
      summary: Delete Conversation Endpoint
      description: 'Delete a conversation and all its history entries.


        Soft-delete by default. When ``hard_delete=True`` and the caller is an

        admin, the conversation and all associated history entries are permanently

        removed from the database.


        Admin access: when the caller is an admin, ownership checks are bypassed,

        allowing cross-user deletion.'
      operationId: delete_conversation_endpoint_v1_conversations__conversation_id__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: conversation_id
        in: path
        required: true
        schema:
          type: string
          title: Conversation Id
      - name: hard_delete
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Hard Delete
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not Found
        '422':
          description: Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically.
        '425':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Too Early
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal Server Error
        '501':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not Implemented
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad Gateway
    patch:
      tags:
      - Conversations
      summary: Recover Conversation Endpoint
      description: Handle PATCH /v1/conversations/{conversation_id} - recover a soft-deleted conversation.
      operationId: recover_conversation_endpoint_v1_conversations__conversation_id__patch
      security:
      - HTTPBearer: []
      parameters:
      - name: conversation_id
        in: path
        required: true
        schema:
          type: string
          title: Conversation Id
      - name: recovery_from_delete
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Recovery From Delete
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationResponse'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not Found
        '422':
          description: Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically.
        '425':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Too Early
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal Server Error
        '501':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not Implemented
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad Gateway
  /v1/conversations/{conversation_id}/responses:
    get:
      tags:
      - Conversations
      summary: List Conversation Responses Endpoint
      description: 'List all responses in a conversation.


        Admin access: when the caller is an admin, ownership checks are bypassed,

        allowing cross-user retrieval of conversation responses.'
      operationId: list_conversation_responses_endpoint_v1_conversations__conversation_id__responses_get
      security:
      - HTTPBearer: []
      parameters:
      - name: conversation_id
        in: path
        required: true
        schema:
          type: string
          title: Conversation Id
      - name: order
        in: query
        required: false
        schema:
          type: string
          default: asc
          title: Order
      - name: include_deleted
        in: query
        required: false
        schema:
          type: boolean
          description: Include soft-deleted responses. Admin-only; returns 403 for non-admin callers.
          default: false
          title: Include Deleted
        description: Include soft-deleted responses. Admin-only; returns 403 for non-admin callers.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationResponsesList'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not Found
        '422':
          description: Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically.
        '425':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Too Early
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal Server Error
        '501':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not Implemented
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad Gateway
components:
  schemas:
    Function:
      properties:
        type:
          type: string
          const: function
          title: Type
          description: Tool type, must be 'function'
        name:
          type: string
          title: Name
          description: Name of the function tool
        parameters:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Parameters
        strict:
          type: boolean
          title: Strict
          default: true
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
      type: object
      required:
      - type
      - name
      title: Function
      description: Function tool definition (client-executed).
    CreateConversationRequest:
      properties:
        metadata:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Metadata
      type: object
      title: CreateConversationRequest
      description: Request body for creating a conversation.
    InputItemMcpApprovalRequest:
      properties:
        type:
          type: string
          const: mcp_approval_request
          title: Type
        id:
          type: string
          pattern: ^mcpr_[a-zA-Z0-9_-]+$
          title: Id
          description: Unique identifier for the approval request
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        server_label:
          anyOf:
          - type: string
          - type: 'null'
          title: Server Label
        arguments:
          anyOf:
          - type: string
          - type: 'null'
          title: Arguments
      type: object
      required:
      - type
      - id
      title: InputItemMcpApprovalRequest
    InputItemReasoning:
      properties:
        type:
          type: string
          const: reasoning
          title: Type
        id:
          type: string
          pattern: ^rs_[a-zA-Z0-9_-]+$
          title: Id
          description: Unique identifier for reasoning messages
        status:
          anyOf:
          - type: string
            enum:
            - in_progress
            - completed
            - incomplete
          - type: 'null'
          title: Status
        role:
          anyOf:
          - type: string
          - type: 'null'
          title: Role
        content:
          anyOf:
          - type: string
          - items:
              $ref: '#/components/schemas/ContentItem'
            type: array
          - items:
              type: string
            type: array
          - type: 'null'
          title: Content
        summary:
          items:
            $ref: '#/components/schemas/ReasoningSummaryItem'
          type: array
          title: Summary
          description: Reasoning summary items returned by the downstream service.
      type: object
      required:
      - type
      - id
      title: InputItemReasoning
      description: Input item for reasoning type messages.
    InputItemFunctionCall:
      properties:
        type:
          type: string
          const: function_call
          title: Type
        call_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Call Id
        id:
          anyOf:
          - type: string
          - type: 'null'
          title: Id
        status:
          anyOf:
          - type: string
            enum:
            - in_progress
            - completed
            - incomplete
          - type: 'null'
          title: Status
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        arguments:
          anyOf:
          - type: string
          - type: 'null'
          title: Arguments
      type: object
      required:
      - type
      title: InputItemFunctionCall
      description: Input item for function call (history reconstruction).
    ConversationListResponse:
      properties:
        object:
          type: string
          title: Object
          default: list
        data:
          items:
            $ref: '#/components/schemas/ConversationResponse'
          type: array
          title: Data
        has_more:
          type: boolean
          title: Has More
        first_id:
          anyOf:
          - type: string
          - type: 'null'
          title: First Id
        last_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Id
      type: object
      required:
      - data
      - has_more
      title: ConversationListResponse
      description: Paginated response for listing conversations.
    InputItemMcpApprovalResponses:
      properties:
        type:
          type: string
          const: mcp_approval_response
          title: Type
        id:
          type: string
          pattern: ^mcpa_[a-zA-Z0-9_-]+$
          title: Id
          description: Unique identifier for the approval response
        approval_request_id:
          type: string
          title: Approval Request Id
        approve:
          type: boolean
          title: Approve
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        arguments:
          anyOf:
          - type: string
          - type: 'null'
          title: Arguments
      type: object
      required:
      - type
      - id
      - approval_request_id
      - approve
      title: InputItemMcpApprovalResponses
    InputItemMessage:
      properties:
        type:
          type: string
          const: message
          title: Type
        id:
          anyOf:
          - type: string
            pattern: ^msg_[a-zA-Z0-9_-]+$
          - type: 'null'
          title: Id
          description: Unique identifier for messages
        status:
          anyOf:
          - type: string
            enum:
            - in_progress
            - completed
            - incomplete
          - type: 'null'
          title: Status
        role:
          anyOf:
          - type: string
          - type: 'null'
          title: Role
        content:
          anyOf:
          - type: string
          - items:
              $ref: '#/components/schemas/ContentItem'
            type: array
          - items:
              type: string
            type: array
          - type: 'null'
          title: Content
      type: object
      required:
      - type
      title: InputItemMessage
      description: 'Input item for structured input.


        Per Open Responses spec, supports:

        - message type: role + content

        - function_call type: call_id + name + arguments (for history)

        - function_call_output type: call_id + output (tool results)


        Fields:

        - id: unique identifier (optional on input, populated on output)

        - status: in_progress, completed, incomplete (optional on input)'
    ConversationResponse:
      properties:
        id:
          type: string
          title: Id
        object:
          type: string
          title: Object
          default: conversation
        metadata:
          additionalProperties:
            type: string
          type: object
          title: Metadata
        created_at:
          type: integer
          title: Created At
        updated_at:
          type: integer
          title: Updated At
      type: object
      required:
      - id
      - created_at
      - updated_at
      title: ConversationResponse
      description: API response schema for conversations — excludes internal fields.
    UsageInfo:
      properties:
        input_tokens:
          type: integer
          title: Input Tokens
        output_tokens:
          type: integer
          title: Output Tokens
        total_tokens:
          type: integer
          title: Total Tokens
      type: object
      required:
      - input_tokens
      - output_tokens
      - total_tokens
      title: UsageInfo
      description: Token usage information.
    ContentItem:
      properties:
        type:
          type: string
          title: Type
          default: output_text
        text:
          type: string
          title: Text
        annotations:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Annotations
      type: object
      required:
      - text
      title: ContentItem
      description: 'Content item in response output.


        Per Open Responses spec:

        - type: output_text, refusal, etc.

        - text: the actual content

        - annotations: optional metadata'
    InputItemFunctionCallOutput:
      properties:
        type:
          type: string
          const: function_call_output
          title: Type
        call_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Call Id
        id:
          anyOf:
          - type: string
          - type: 'null'
          title: Id
        status:
          anyOf:
          - type: string
            enum:
            - in_progress
            - completed
            - incomplete
          - type: 'null'
          title: Status
        output:
          anyOf:
          - type: string
          - type: 'null'
          title: Output
      type: object
      required:
      - type
      title: InputItemFunctionCallOutput
      description: Input item for function call (history reconstruction).
    UpdateConversationRequest:
      properties:
        metadata:
          additionalProperties:
            type: string
          type: object
          title: Metadata
      type: object
      required:
      - metadata
      title: UpdateConversationRequest
      description: Request body for updating conversation metadata.
    InputItemMcpCall:
      properties:
        type:
          type: string
          const: mcp_call
          title: Type
        id:
          type: string
          pattern: ^mcp_[a-zA-Z0-9_-]+$
          title: Id
          description: Unique identifier for the MCP call
        name:
          type: string
          title: Name
        arguments:
          anyOf:
          - type: string
          - type: 'null'
          title: Arguments
        server_label:
          anyOf:
          - type: string
          - type: 'null'
          title: Server Label
        output:
          anyOf:
          - type: string
          - type: 'null'
          title: Output
      type: object
      required:
      - type
      - id
      - name
      title: InputItemMcpCall
    InputItemMcpListTools:
      properties:
        type:
          type: string
          const: mcp_list_tools
          title: Type
        id:
          type: string
          pattern: ^mcpl_[a-zA-Z0-9_-]+$
          title: Id
          description: Unique identifier for the MCP list tools
        server_label:
          anyOf:
          - type: string
          - type: 'null'
          title: Server Label
        tools:
          anyOf:
          - additionalProperties: true
            type: object
          - items: {}
            type: array
          - type: 'null'
          title: Tools
      type: object
      required:
      - type
      - id
      title: InputItemMcpListTools
    ReasoningSummaryItem:
      properties:
        type:
          type: string
          const: summary_text
          title: Type
        text:
          type: string
          title: Text
      type: object
      required:
      - type
      - text
      title: ReasoningSummaryItem
      description: Summary item for reasoning output messages.
    MCPTool:
      properties:
        type:
          type: string
          const: mcp
          title: Type
          description: Tool type, must be 'mcp'
        require_approval:
          type: string
          enum:
          - always
          - never
          title: Require Approval
          description: Whether the server requires approval before calling the tool. 'always' means approval is required, 'never' means no approval needed.
          default: always
        server_label:
          anyOf:
          - type: string
          - type: 'null'
          title: Server Label
          description: Optional label for the tool to be used by the server
        allowed_tools:
          anyOf:
          - additionalProperties: true
            type: object
          - items:
              type: string
            type: array
          - type: 'null'
          title: Allowed Tools
          description: Optional dict or array of allowed tools that the server can call, keyed by tool name. This can be used to specify which tools the server is allowed to call, and can include additional configuration for each tool.
        authorization:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
          description: Optional authorization information for the server to use when calling the tool. This can include API keys, tokens, or other credentials needed to access the tool.
        headers:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Headers
          descri

# --- truncated at 32 KB (42 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/aleph-alpha/refs/heads/main/openapi/aleph-alpha-conversations-api-openapi.yml