Events.com Python Agent API

openapi: 3.2.0
info:
  title: DataGol AI Python Agent API
  version: 1.0.36
tags:
- name: Python Agent
paths:
  /ai/api/v2/python-agent/query:
    post:
      tags:
      - Python Agent
      summary: Query Agent Unified
      description: 'Single endpoint: ensure session exists using conversationId; then stream query using existing flow.'
      operationId: query_agent_unified_ai_api_v2_python_agent_query_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /ai/api/v2/python-agent/ui:
    get:
      tags:
      - Python Agent
      summary: Python Agent Ui
      description: Serve plain HTML chat UI for python-agent ask/stop flows.
      operationId: python_agent_ui_ai_api_v2_python_agent_ui_get
      responses:
        '200':
          description: Successful Response
          content:
            text/html:
              schema:
                type: string
  /ai/api/v2/python-agent/submit-feedback:
    post:
      tags:
      - Python Agent
      summary: Submit Feedback
      description: Submit feedback and immediately continue streaming for the same session.
      operationId: submit_feedback_ai_api_v2_python_agent_submit_feedback_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PythonAgentFeedbackRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /ai/api/v2/python-agent/{conversation_id}/{message_id}/stop:
    post:
      tags:
      - Python Agent
      summary: Stop Python Agent Run
      description: Stop an active python-agent run by conversation and message id.
      operationId: stop_python_agent_run_ai_api_v2_python_agent__conversation_id___message_id__stop_post
      parameters:
      - name: conversation_id
        in: path
        required: true
        schema:
          type: string
          title: Conversation Id
      - name: message_id
        in: path
        required: true
        schema:
          type: string
          title: Message Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StopRunResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /ai/api/v2/python-agent/session/{session_id}/status:
    get:
      tags:
      - Python Agent
      summary: Get Session Info
      description: Get the status of a Python agent session
      operationId: get_session_info_ai_api_v2_python_agent_session__session_id__status_get
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          title: Session Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PythonAgentResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /ai/api/v2/python-agent/sessions:
    get:
      tags:
      - Python Agent
      summary: Get All Sessions
      description: Get all active sessions with their stale status
      operationId: get_all_sessions_ai_api_v2_python_agent_sessions_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PythonAgentResponse'
  /ai/api/v2/python-agent/session/{session_id}:
    delete:
      tags:
      - Python Agent
      summary: Cleanup Session
      description: Clean up a Python agent session
      operationId: cleanup_session_ai_api_v2_python_agent_session__session_id__delete
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          title: Session Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PythonAgentResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /ai/api/v2/python-agent/cleanup-stale-sessions:
    post:
      tags:
      - Python Agent
      summary: Cleanup Stale Sessions
      description: 'Automatically find and cleanup all stale sessions (inactive > 10 minutes).

        Removes agent instances and frees memory for sessions that meet the stale criteria.'
      operationId: cleanup_stale_sessions_ai_api_v2_python_agent_cleanup_stale_sessions_post
      parameters:
      - name: token
        in: query
        required: true
        schema:
          type: string
          description: Authentication token for cleanup operation
          title: Token
        description: Authentication token for cleanup operation
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PythonAgentResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /ai/api/v2/python-agent/get-plotly:
    get:
      tags:
      - Python Agent
      summary: Get Plotly Json
      description: 'Endpoint to retrieve plotly JSON configuration from storage (AWS S3 or GCP).


        Args:

        key: Storage key path (e.g., "python_agent/plotly_configs/session_id/message_id/chart.json")


        Returns:

        JSON: The plotly chart configuration'
      operationId: get_plotly_json_ai_api_v2_python_agent_get_plotly_get
      parameters:
      - name: key
        in: query
        required: true
        schema:
          type: string
          description: Storage key path to the plotly JSON file
          title: Key
        description: Storage key path to the plotly JSON file
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AgentRequest:
      properties:
        userId:
          anyOf:
          - type: integer
          - type: 'null'
          title: Userid
          description: 'ID of the user sending this query. '
        conversationId:
          type: string
          title: Conversationid
          description: Conversation or thread ID of the query.
        message:
          type: string
          title: Message
          description: User query or message to the agent.
        selectedLlmModel:
          anyOf:
          - type: string
          - type: 'null'
          title: Selectedllmmodel
          description: Model to be used to resolve the query.
        parameters:
          $ref: '#/components/schemas/Parameters'
          description: Context for the query
        agentType:
          type: string
          title: Agenttype
          description: 'Type of agent. Example: PythonAgent, DataConversationAgent, SQLAgent, BIAgent, etc.'
        selectedParser:
          type: string
          title: Selectedparser
          description: 'Type of parser. Example: LLM Sherpa, Llama Parse'
        workbookIds:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Workbookids
          description: List of workbook IDs for additional data sources.
        callerMessageId:
          anyOf:
          - type: integer
          - type: 'null'
          title: Callermessageid
          description: Pre-allocated message ID from ai-core. When set, skips internal DB INSERT and UPDATE.
        callerUserId:
          anyOf:
          - type: string
          - type: 'null'
          title: Calleruserid
          description: User ID pre-validated by ai-core.
      type: object
      required:
      - message
      - parameters
      - agentType
      title: AgentRequest
    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
    PythonAgentFeedbackRequest:
      properties:
        session_id:
          type: string
          title: Session Id
        feedback:
          type: string
          title: Feedback
        chain_id:
          type: string
          title: Chain Id
        query_clarification:
          type: string
          title: Query Clarification
        context_needed:
          type: string
          title: Context Needed
      type: object
      required:
      - session_id
      - feedback
      - chain_id
      - query_clarification
      - context_needed
      title: PythonAgentFeedbackRequest
      description: Request model for Python agent feedback submission
    StopRunResponse:
      properties:
        status:
          type: string
          title: Status
        message:
          type: string
          title: Message
        messageId:
          type: string
          title: Messageid
        conversationId:
          anyOf:
          - type: string
          - type: 'null'
          title: Conversationid
        agentType:
          anyOf:
          - type: string
          - type: 'null'
          title: Agenttype
          default: PythonAgent
        disconnectInvoked:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Disconnectinvoked
          default: false
      type: object
      required:
      - status
      - message
      - messageId
      title: StopRunResponse
      description: Response model for stop endpoint.
    PythonAgentResponse:
      properties:
        message:
          type: string
          title: Message
        status:
          type: string
          title: Status
          default: success
        data:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Data
      type: object
      required:
      - message
      title: PythonAgentResponse
      description: Base response model for Python agent
    Parameters:
      properties:
        dataProvider:
          anyOf:
          - type: string
          - type: 'null'
          title: Dataprovider
          description: Provider if that is the context.
        viewId:
          anyOf:
          - type: string
          - type: 'null'
          title: Viewid
          description: View ID if that is the context.
        workbookId:
          anyOf:
          - type: string
          - type: 'null'
          title: Workbookid
          description: Workbook ID if that is the context.
        workspaceId:
          anyOf:
          - type: string
          - type: 'null'
          title: Workspaceid
          description: Workspace ID if that is the context.
        dataSourceId:
          anyOf:
          - items:
              type: integer
            type: array
          - type: 'null'
          title: Datasourceid
          description: List of Datasource IDs if that is the context.
        dataSourceIds:
          anyOf:
          - items:
              type: integer
            type: array
          - type: 'null'
          title: Datasourceids
          description: List of Datasource IDs if that is the context.
        tableId:
          anyOf:
          - type: string
          - type: 'null'
          title: Tableid
          description: Table/Workbook ID if that is the context. BI Agent specific.
        fileIds:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Fileids
          description: File IDs if that is the context.
        schemaJson:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Schemajson
          description: Schema of the data source.
        dialect:
          anyOf:
          - type: string
          - type: 'null'
          title: Dialect
          description: 'Dialect of the query. Example: JDBC, SPARK, etc.'
        toolsSelected:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Toolsselected
          description: List of tools selected by the user.
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Error message if any.
        folderName:
          anyOf:
          - type: string
          - type: 'null'
          title: Foldername
          description: Complete hierarchy of the folder name.
        connectorId:
          anyOf:
          - type: integer
          - type: 'null'
          title: Connectorid
          description: Connector ID of the Jira connector.
        customAgentId:
          anyOf:
          - type: string
          - type: 'null'
          title: Customagentid
          description: Custom Agent ID.
        sqlQuery:
          anyOf:
          - type: string
          - type: 'null'
          title: Sqlquery
          description: SQL query for generating a workbook
        enableBiHistory:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Enablebihistory
          description: Enable BI history for the query.
          default: true
        selectedLlmModels:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Selectedllmmodels
          description: Map of selected llm models.
        chainId:
          anyOf:
          - type: string
          - type: 'null'
          title: Chainid
          description: Chain ID of the query.
        image:
          anyOf:
          - type: string
          - type: 'null'
          title: Image
          description: plolty chart Image.
        code:
          anyOf:
          - type: string
          - type: 'null'
          title: Code
          description: Python code to execute. If provided, no planning/code generation will be done.
        workbookIds:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Workbookids
          description: Selected workbooks in the same workspace as workbookId; first item duplicates workbookId (primary); remaining IDs are auxiliary.
        autoApprove:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Autoapprove
          description: When True or omitted, agent does not prompt for plan/code confirmation and proceeds automatically. When False, requires user confirmation.
        analysisLevel:
          anyOf:
          - type: string
            enum:
            - FAST
            - MODERATE
            - DEEP_ANALYSIS
          - type: 'null'
          title: Analysislevel
          description: 'LLM profile: "FAST" (Groq fast_agent_configs), "MODERATE" (standard_agent_configs), "DEEP_ANALYSIS" (top-level agent_configs). Omitted or null defaults to DEEP_ANALYSIS. Case-insensitive and legacy labels Fast / Moderate / Deep Analysis are accepted.'
      type: object
      title: Parameters
x-provenance:
  method: harvested
  publisher: Events.com
  source: https://datagol-python.events.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)