openapi: 3.0.3
info:
  title: Maven AGI Platform Actions Conversations API
  version: '1.0'
  description: The Maven AGI Platform API lets developers build apps on the Maven AGI enterprise AI agent platform. It exposes conversations, knowledge, actions, users, agents, events, triggers, app settings, and analytics. Requests authenticate with an App ID and App Secret supplied as HTTP Basic credentials, together with X-Organization-Id and X-Agent-Id headers that scope the request to a specific organization and agent. Paths in this document are relative to the /v1 base path.
  contact:
    name: Maven AGI
    url: https://docs.mavenagi.com
  license:
    name: Proprietary
servers:
- url: https://www.mavenagi-apis.com/v1
  description: Production
- url: https://www.staging.mavenagi-apis.com/v1
  description: Staging
security:
- appAuth: []
tags:
- name: Conversations
paths:
  /conversations:
    post:
      tags:
      - Conversations
      operationId: initializeConversation
      summary: Initialize a conversation
      description: Create and initialize a new conversation for the agent.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationRequest'
      responses:
        '200':
          description: The initialized conversation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
  /conversations/{conversationId}:
    parameters:
    - $ref: '#/components/parameters/ConversationId'
    get:
      tags:
      - Conversations
      operationId: getConversation
      summary: Get a conversation
      responses:
        '200':
          description: The requested conversation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
    patch:
      tags:
      - Conversations
      operationId: patchConversation
      summary: Patch a conversation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The updated conversation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
    delete:
      tags:
      - Conversations
      operationId: deleteConversation
      summary: Delete a conversation
      responses:
        '204':
          description: Conversation deleted.
  /conversations/{conversationId}/messages:
    parameters:
    - $ref: '#/components/parameters/ConversationId'
    post:
      tags:
      - Conversations
      operationId: appendNewMessages
      summary: Append new messages
      description: Append one or more new messages to an existing conversation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The updated conversation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
  /conversations/{conversationId}/ask:
    parameters:
    - $ref: '#/components/parameters/ConversationId'
    post:
      tags:
      - Conversations
      operationId: ask
      summary: Ask the agent a question
      description: Send a user message and receive the agent's answer, including any actions taken and knowledge referenced.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AskRequest'
      responses:
        '200':
          description: The agent's response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationMessage'
  /conversations/{conversationId}/ask_stream:
    parameters:
    - $ref: '#/components/parameters/ConversationId'
    post:
      tags:
      - Conversations
      operationId: askStream
      summary: Ask the agent a question (streaming)
      description: Same as ask, but streams the response back as Server-Sent Events for low-latency, incremental delivery.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AskRequest'
      responses:
        '200':
          description: A stream of response events.
          content:
            text/event-stream:
              schema:
                type: string
  /conversations/{conversationId}/categorize:
    parameters:
    - $ref: '#/components/parameters/ConversationId'
    post:
      tags:
      - Conversations
      operationId: categorizeConversation
      summary: Categorize a conversation
      responses:
        '200':
          description: Categorization result.
          content:
            application/json:
              schema:
                type: object
  /conversations/{conversationId}/submit-form:
    parameters:
    - $ref: '#/components/parameters/ConversationId'
    post:
      tags:
      - Conversations
      operationId: submitActionForm
      summary: Submit an action form
      description: Submit the collected parameters for an action form the agent presented.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The updated conversation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
  /conversations/{conversationId}/metadata:
    parameters:
    - $ref: '#/components/parameters/ConversationId'
    post:
      tags:
      - Conversations
      operationId: addConversationMetadata
      summary: Add conversation metadata
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties:
                type: string
      responses:
        '200':
          description: The updated metadata.
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
    put:
      tags:
      - Conversations
      operationId: updateConversationMetadata
      summary: Update conversation metadata
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties:
                type: string
      responses:
        '200':
          description: The updated metadata.
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
  /conversations/feedback:
    post:
      tags:
      - Conversations
      operationId: createFeedback
      summary: Create conversation feedback
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The created feedback.
          content:
            application/json:
              schema:
                type: object
  /conversations/search:
    post:
      tags:
      - Conversations
      operationId: searchConversations
      summary: Search conversations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Matching conversations.
          content:
            application/json:
              schema:
                type: object
  /conversations/export:
    post:
      tags:
      - Conversations
      operationId: exportConversations
      summary: Export conversations
      responses:
        '200':
          description: Exported conversation data.
          content:
            application/json:
              schema:
                type: object
  /conversations/deliver-message:
    post:
      tags:
      - Conversations
      operationId: deliverMessage
      summary: Deliver a message
      description: Deliver an outbound message to a conversation channel.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Delivery result.
          content:
            application/json:
              schema:
                type: object
components:
  schemas:
    EntityId:
      type: object
      description: A reference identifier scoped to a type.
      properties:
        referenceId:
          type: string
        type:
          type: string
        appId:
          type: string
    Conversation:
      type: object
      properties:
        conversationId:
          $ref: '#/components/schemas/EntityId'
        messages:
          type: array
          items:
            $ref: '#/components/schemas/ConversationMessage'
        subject:
          type: string
        createdAt:
          type: string
          format: date-time
        metadata:
          type: object
          additionalProperties:
            type: string
    ConversationMessage:
      type: object
      properties:
        conversationMessageId:
          $ref: '#/components/schemas/EntityId'
        userId:
          $ref: '#/components/schemas/EntityId'
        text:
          type: string
        responseLength:
          type: string
          enum:
          - SHORT
          - MEDIUM
          - LONG
    AskRequest:
      type: object
      required:
      - conversationMessageId
      - userId
      - text
      properties:
        conversationMessageId:
          $ref: '#/components/schemas/EntityId'
        userId:
          $ref: '#/components/schemas/EntityId'
        text:
          type: string
        attachments:
          type: array
          items:
            type: object
    ConversationRequest:
      type: object
      properties:
        conversationId:
          $ref: '#/components/schemas/EntityId'
        messages:
          type: array
          items:
            $ref: '#/components/schemas/ConversationMessage'
        subject:
          type: string
        tags:
          type: array
          items:
            type: string
        metadata:
          type: object
          additionalProperties:
            type: string
  parameters:
    ConversationId:
      name: conversationId
      in: path
      required: true
      schema:
        type: string
  securitySchemes:
    appAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication using the App ID as the username and the App Secret as the password. Requests must also send X-Organization-Id and X-Agent-Id headers to scope the call to an organization and agent.