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:
    ConversationResponsesList:
      properties:
        object:
          type: string
          title: Object
          default: list
        data:
          items:
            $ref: '#/components/schemas/ConversationResponseItem'
          type: array
          title: Data
      type: object
      required:
      - data
      title: ConversationResponsesList
      description: Response for listing all responses in a conversation.
    CreateConversationRequest:
      properties:
        metadata:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Metadata
      type: object
      title: CreateConversationRequest
      description: Request body for creating a conversation.
    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.
    ConversationResponseItem:
      properties:
        id:
          type: string
          title: Id
          description: The unique ID of the response.
        object:
          type: string
          title: Object
          description: The object type.
          default: response
        created_at:
          type: integer
          title: Created At
          description: The Unix timestamp (in seconds) for when the response was created.
        completed_at:
          anyOf:
          - type: integer
          - type: 'null'
          title: Completed At
          description: The Unix timestamp (in seconds) for when the response was completed.
        status:
          type: string
          title: Status
          description: The status of the response.
          default: completed
        incomplete_details:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Incomplete Details
          description: Details about why the response was incomplete, if applicable.
        model:
          type: string
          title: Model
          description: The model that generated this response.
        previous_response_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Previous Response Id
          description: The ID of the previous response in the conversation chain, if any.
        instructions:
          anyOf:
          - type: string
          - type: 'null'
          title: Instructions
          description: Additional instructions used to guide the model for this response.
        output:
          items:
            oneOf:
            - $ref: '#/components/schemas/InputItemMessage'
            - $ref: '#/components/schemas/InputItemReasoning'
            - $ref: '#/components/schemas/InputItemFunctionCall'
            - $ref: '#/components/schemas/InputItemFunctionCallOutput'
            - $ref: '#/components/schemas/InputItemMcpApprovalRequest'
            - $ref: '#/components/schemas/InputItemMcpApprovalResponses'
            - $ref: '#/components/schemas/InputItemMcpListTools'
            - $ref: '#/components/schemas/InputItemMcpCall'
            description: Input item type, used to determine the input item schema
            discriminator:
              propertyName: type
              mapping:
                function_call: '#/components/schemas/InputItemFunctionCall'
                function_call_output: '#/components/schemas/InputItemFunctionCallOutput'
                mcp_approval_request: '#/components/schemas/InputItemMcpApprovalRequest'
                mcp_approval_response: '#/components/schemas/InputItemMcpApprovalResponses'
                mcp_call: '#/components/schemas/InputItemMcpCall'
                mcp_list_tools: '#/components/schemas/InputItemMcpListTools'
                message: '#/components/schemas/InputItemMessage'
                reasoning: '#/components/schemas/InputItemReasoning'
          type: array
          title: Output
          description: The output items generated by the model.
        error:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Error
          description: The error that occurred, if the response failed.
        tools:
          items:
            oneOf:
            - $ref: '#/components/schemas/Function'
            - $ref: '#/components/schemas/MCPTool'
            description: Tool type, used to determine the tool schema
            discriminator:
              propertyName: type
              mapping:
                function: '#/components/schemas/Function'
                mcp: '#/components/schemas/MCPTool'
          type: array
          title: Tools
          description: The tools available to the model during response generation.
        tool_choice:
          anyOf:
          - type: string
            enum:
            - auto
            - required
            - none
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Tool Choice
          description: Controls which tool the model should use, if any.
        truncation:
          anyOf:
          - type: string
          - type: 'null'
          title: Truncation
          description: How the input was truncated when it exceeded the model context window.
        parallel_tool_calls:
          type: boolean
          title: Parallel Tool Calls
          description: Whether the model was allowed to call multiple tools in parallel.
          default: true
        text:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Text
          description: Configuration options for text output.
        top_p:
          anyOf:
          - type: number
          - type: 'null'
          title: Top P
          description: The nucleus sampling parameter used for this response.
        temperature:
          anyOf:
          - type: number
          - type: 'null'
          title: Temperature
          description: The sampling temperature used for this response.
        presence_penalty:
          anyOf:
          - type: number
          - type: 'null'
          title: Presence Penalty
          description: Penalizes new tokens based on whether they appear in the text so far.
        frequency_penalty:
          anyOf:
          - type: number
          - type: 'null'
          title: Frequency Penalty
          description: Penalizes new tokens based on their frequency in the text so far.
        top_logprobs:
          anyOf:
          - type: integer
          - type: 'null'
          title: Top Logprobs
          description: Number of most likely tokens returned at each position.
        reasoning:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Reasoning
          description: Reasoning configuration and outputs produced for this response.
        usage:
          $ref: '#/components/schemas/UsageInfo'
          description: Token usage statistics for the response.
        max_output_tokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Output Tokens
          description: The maximum number of tokens the model was allowed to generate.
        max_tool_calls:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Tool Calls
          description: The maximum number of tool calls the model was allowed to make.
        store:
          type: boolean
          title: Store
          description: Whether this response was stored for later retrieval.
          default: true
        background:
          type: boolean
          title: Background
          description: Whether this request was run in the background.
          default: false
        service_tier:
          anyOf:
          - type: string
          - type: 'null'
          title: Service Tier
          description: The service tier used for this response.
        metadata:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Metadata
          description: Key-value pairs for storing additional information about the response.
        prompt_cache_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Prompt Cache Key
          description: A key used to read from or write to the prompt cache.
        conversation:
          anyOf:
          - $ref: '#/components/schemas/ConversationRef'
          - type: 'null'
          description: The conversation this response belongs to, if any.
        safety_identifier:
          anyOf:
          - type: string
          - type: 'null'
          title: Safety Identifier
          description: A stable identifier used for safety monitoring and abuse detection.
        ancestor_ids:
          items:
            type: string
          type: array
          title: Ancestor Ids
        depth:
          type: integer
          title: Depth
        request_input:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Request Input
      type: object
      required:
      - id
      - created_at
      - model
      - output
      - usage
      - ancestor_ids
      - depth
      - request_input
      title: ConversationResponseItem
      description: Full response plus tree metadata and user input for conversation listing.
    ErrorDetail:
      properties:
        message:
          type: string
          title: Message
        type:
          type: string
          title: Type
        param:
          anyOf:
          - type: string
          - type: 'null'
          title: Param
        code:
          anyOf:
          - type: string
          - type: 'null'
          title: Code
      type: object
      required:
      - message
      - type
      title: ErrorDetail
      description: Structured error detail matching the OpenAI Responses API convention.
    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
    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.
    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:

# --- 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