Ask Sage Execute Agent API

openapi: 3.0.3
info:
  title: Ask Sage Server Admin Execute Agent API
  description: 'Ask Sage is an AI-powered platform providing intelligent completions, knowledge management, and workflow automation.


    ## Base URL

    `https://api.asksage.ai`


    ## Authentication

    All endpoints require a valid JWT token passed via the `x-access-tokens` header, unless otherwise noted.


    Obtain a token by authenticating through the User API (`/user/get-token-with-api-key`).


    ## Message Format

    The `message` field in API requests can be either:

    - A single string prompt: `"What is Ask Sage?"`

    - An array of conversation messages: `[{"user": "me", "message": "what is Ask Sage?"}, {"user": "gpt", "message": "Ask Sage is an..."}]`


    ## Key Features

    - **AI Completions** — Query multiple LLM providers with a unified interface

    - **Knowledge Training** — Upload documents, files, and data to build custom datasets

    - **Tabular Data** — Ingest and query structured data (CSV, XLSX) with natural language

    - **Agent Builder** — Create, configure, and execute multi-step AI workflows

    - **Plugins** — Extend capabilities with built-in and custom plugins

    - **MCP Servers** — Connect to Model Context Protocol servers for tool integration'
  version: '2.0'
  contact:
    name: Ask Sage Support
    email: support@asksage.ai
    url: https://asksage.ai
servers:
- url: '{baseUrl}/server'
  description: Ask Sage Server API
  variables:
    baseUrl:
      default: https://api.asksage.ai
      description: API base URL. Use https://api.asksage.ai for production, or your self-hosted instance URL.
security:
- ApiKeyAuth: []
tags:
- name: Execute Agent
paths:
  /execute-agent:
    post:
      summary: Execute Agent
      description: 'Executes a specific agent with a message and optional parameters. Supports both non-streaming (JSON) and streaming (Server-Sent Events) responses.

        '
      operationId: execute_agent_ep
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - agent_id
              - message
              properties:
                agent_id:
                  type: integer
                  description: ID of the agent to execute.
                message:
                  type: string
                  description: The user's message/prompt to the agent.
                streaming:
                  type: boolean
                  description: If true, enables a Server-Sent Events (SSE) stream. If false, returns a single JSON response.
                  default: true
                variables:
                  type: object
                  description: A JSON object of runtime variables. For file variables, the value should be the filename of a file uploaded via a multipart/form-data request.
                  example:
                    priority: high
                    source_data: data.csv
                conversation_history:
                  type: array
                  description: A JSON array representing the conversation history.
                  items:
                    type: object
                    properties:
                      message:
                        type: string
                      user:
                        type: string
                        enum:
                        - me
                        - system
          multipart/form-data:
            schema:
              type: object
              required:
              - agent_id
              - message
              properties:
                agent_id:
                  type: integer
                message:
                  type: string
                streaming:
                  type: string
                  enum:
                  - 'true'
                  - 'false'
                  default: 'true'
                variables:
                  type: string
                  description: A JSON string of runtime variables. The value for a file variable must match the filename of an uploaded file.
                  example: '{"priority": "high", "source_data": "data.csv"}'
                conversation_history:
                  type: string
                  description: A JSON string of the conversation history array.
                file:
                  type: string
                  format: binary
                  description: A file to be processed. To upload multiple files, provide multiple form parts with the same 'file' key.
      responses:
        '200':
          description: 'Agent execution initiated. The response format depends on the `streaming` parameter and the `Accept` header.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentExecutionResponse'
            text/plain:
              schema:
                type: string
              description: 'A Server-Sent Events (SSE) stream, sent when `streaming: true`. The stream consists of multiple JSON objects, each preceded by `data: ` and followed by `\n\n`.

                **Event Types:** Each JSON object has an `event` field. Key events include: - `workflow_started`: Signals the beginning of execution. - `node_completed`: A node finished successfully. Contains `data.output`. - `node_error`: A node failed. Contains `data.error`. - `workflow_completed`: The workflow finished. Contains final `data.output`. - `agent_response`: The final, processed response from the agent.

                **Example Event:** `data: {"event": "node_completed", "data": {"node_id": "llm_1", "output": {"response": "Hello!"}}, "timestamp": "..."}\n\n`

                '
        '400':
          description: Bad request - check agent_id and variables.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Authentication failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Agent not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '413':
          description: Request payload too large.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Execution error - see error field for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutionError'
        '504':
          description: Timeout - agent execution took too long.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutionError'
      tags:
      - Execute Agent
components:
  schemas:
    ExecutionError:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        details:
          type: string
    ApiError:
      type: object
      properties:
        error:
          type: string
          description: Error message
        status:
          type: integer
          description: HTTP status code
        details:
          type: string
          description: Additional error details
      required:
      - error
    AgentExecutionResponse:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code
          example: 200
        execution_status:
          type: string
          enum:
          - completed
          - failed
          - timeout
          description: Status of the agent execution
        execution_id:
          type: integer
          description: Unique identifier for this execution
        duration_ms:
          type: integer
          description: Execution duration in milliseconds
        response:
          type: object
          properties:
            response:
              type: string
              description: The agent's final response text
            type:
              type: string
              description: Type of response (e.g., "text")
            source:
              type: string
              description: Source node of the response
        workflow:
          type: object
          description: Details of the primary workflow that was executed
          properties:
            id:
              type: integer
              description: The workflow's numeric ID
            uuid:
              type: string
              format: uuid
              description: The workflow's unique identifier
            name:
              type: string
              description: The name of the workflow
            version:
              type: integer
              description: The version number of the workflow that was executed
        node_executions:
          type: array
          description: A step-by-step log of each node's execution within the workflow
          items:
            type: object
            properties:
              node_id:
                type: string
                description: The unique identifier of the node
              node_type:
                type: string
                description: The type of node (e.g., "llm", "condition")
              status:
                type: string
                enum:
                - completed
                - failed
                description: The execution status of the node
              output:
                type: object
                nullable: true
                description: The output produced by the node if successful
              error:
                type: object
                nullable: true
                description: Error details if the node failed
              metadata:
                type: object
                nullable: true
                description: Additional metadata about the node execution
        error:
          type: string
          nullable: true
          description: Error message if execution failed
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-access-tokens
      description: JWT authentication token. Obtain a token by calling the User API endpoint `/user/get-token-with-api-key` with your email and API key.