openapi: 3.0.3 info: title: Ask Sage Server Admin Agent Builder 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: Agent Builder description: Agent builder workflow and agent management paths: /create-workflow: post: summary: Create workflow description: Create a new workflow for the agent builder tags: - Agent Builder requestBody: required: true content: application/json: schema: type: object required: - name properties: name: type: string minLength: 1 maxLength: 255 pattern: ^[a-zA-Z0-9\s\-_.]+$ description: Workflow name description: type: string maxLength: 1000 description: Workflow description initial_dsl: type: object description: Initial DSL definition for the workflow responses: '200': description: Workflow created successfully content: application/json: schema: type: object properties: response: type: string workflow: type: object status: type: integer '400': description: Bad request '409': description: Duplicate workflow name /get-workflow: get: summary: Get workflow description: Get workflow by ID tags: - Agent Builder requestBody: required: true content: application/json: schema: type: object required: - workflow_id properties: workflow_id: type: integer description: Workflow ID responses: '200': description: Workflow retrieved '404': description: Workflow not found post: summary: Get workflow (POST) description: Get workflow by ID tags: - Agent Builder requestBody: required: true content: application/json: schema: type: object required: - workflow_id properties: workflow_id: type: integer description: Workflow ID responses: '200': description: Workflow retrieved '404': description: Workflow not found /list-workflows: get: summary: List workflows description: List workflows for user with pagination tags: - Agent Builder parameters: - name: limit in: query schema: type: integer default: 20 maximum: 100 - name: offset in: query schema: type: integer default: 0 responses: '200': description: Workflows listed content: application/json: schema: type: object properties: response: type: array items: type: object count: type: integer total: type: integer limit: type: integer offset: type: integer status: type: integer post: summary: List workflows (POST) description: List workflows for user with pagination tags: - Agent Builder requestBody: content: application/json: schema: type: object properties: limit: type: integer default: 20 maximum: 100 offset: type: integer default: 0 responses: '200': description: Workflows listed /delete-workflow: delete: summary: Delete workflow description: Soft delete a workflow tags: - Agent Builder requestBody: required: true content: application/json: schema: type: object required: - workflow_id properties: workflow_id: type: integer responses: '200': description: Workflow deleted '404': description: Workflow not found post: summary: Delete workflow (POST) description: Soft delete a workflow tags: - Agent Builder requestBody: required: true content: application/json: schema: type: object required: - workflow_id properties: workflow_id: type: integer responses: '200': description: Workflow deleted '404': description: Workflow not found /save-workflow-version: post: summary: Save workflow version description: Save a new version of workflow DSL tags: - Agent Builder requestBody: required: true content: application/json: schema: type: object required: - workflow_id - dsl_definition properties: workflow_id: type: integer dsl_definition: type: object description: DSL definition for the workflow version changelog: type: string maxLength: 1000 description: Version changelog auto_save: type: boolean default: false description: Whether this is an auto-save responses: '200': description: Version saved successfully content: application/json: schema: type: object properties: response: type: string version: type: object properties: id: type: integer version_number: type: integer created_at: type: string format: date-time status: type: integer /get-workflow-version: get: summary: Get workflow version description: Get workflow version DSL by version_id or workflow_id tags: - Agent Builder requestBody: content: application/json: schema: type: object properties: version_id: type: integer description: Specific version ID workflow_id: type: integer description: Workflow ID (returns current version) responses: '200': description: Version retrieved post: summary: Get workflow version (POST) description: Get workflow version DSL by version_id or workflow_id tags: - Agent Builder requestBody: content: application/json: schema: type: object properties: version_id: type: integer workflow_id: type: integer responses: '200': description: Version retrieved /list-workflow-versions: get: summary: List workflow versions description: List all versions of a workflow tags: - Agent Builder requestBody: required: true content: application/json: schema: type: object required: - workflow_id properties: workflow_id: type: integer responses: '200': description: Versions listed post: summary: List workflow versions (POST) description: List all versions of a workflow tags: - Agent Builder requestBody: required: true content: application/json: schema: type: object required: - workflow_id properties: workflow_id: type: integer responses: '200': description: Versions listed /create-agent: post: summary: Create agent description: Create a new agent for the agent builder tags: - Agent Builder requestBody: required: true content: application/json: schema: type: object required: - name - primary_workflow_uuid properties: name: type: string minLength: 1 maxLength: 255 pattern: ^[a-zA-Z0-9\s\-_.]+$ description: type: string maxLength: 1000 agent_mode: type: string enum: - single default: single description: Agent execution mode (only 'single' currently supported) primary_workflow_uuid: type: string format: uuid description: UUID of the primary workflow system_prompt: type: string maxLength: 5000 model: type: string description: Default model for the agent temperature: type: number default: 1.0 variables: type: object description: Agent variable definitions responses: '200': description: Agent created '409': description: Duplicate agent name /get-agent: get: summary: Get agent description: Get agent by ID tags: - Agent Builder requestBody: required: true content: application/json: schema: type: object required: - agent_id properties: agent_id: type: integer responses: '200': description: Agent retrieved '404': description: Agent not found post: summary: Get agent (POST) description: Get agent by ID tags: - Agent Builder requestBody: required: true content: application/json: schema: type: object required: - agent_id properties: agent_id: type: integer responses: '200': description: Agent retrieved '404': description: Agent not found /update-agent: put: summary: Update agent description: Update agent configuration (creates new version) tags: - Agent Builder requestBody: required: true content: application/json: schema: type: object required: - agent_id properties: agent_id: type: integer name: type: string maxLength: 255 description: type: string maxLength: 1000 primary_workflow_uuid: type: string format: uuid system_prompt: type: string maxLength: 5000 variables: type: object changelog: type: string responses: '200': description: Agent updated '404': description: Agent not found '409': description: Duplicate name post: summary: Update agent (POST) description: Update agent configuration (creates new version) tags: - Agent Builder requestBody: required: true content: application/json: schema: type: object required: - agent_id properties: agent_id: type: integer name: type: string maxLength: 255 description: type: string maxLength: 1000 primary_workflow_uuid: type: string format: uuid system_prompt: type: string maxLength: 5000 variables: type: object changelog: type: string responses: '200': description: Agent updated '404': description: Agent not found '409': description: Duplicate name /delete-agent: delete: summary: Delete agent description: Soft delete an agent tags: - Agent Builder requestBody: required: true content: application/json: schema: type: object required: - agent_id properties: agent_id: type: integer responses: '200': description: Agent deleted '404': description: Agent not found post: summary: Delete agent (POST) description: Soft delete an agent tags: - Agent Builder requestBody: required: true content: application/json: schema: type: object required: - agent_id properties: agent_id: type: integer responses: '200': description: Agent deleted '404': description: Agent not found /list-node-templates: get: summary: List node templates description: List available node templates for the workflow builder. Templates are dynamically generated from registered node classes. tags: - Agent Builder responses: '200': description: Node templates listed content: application/json: schema: type: object properties: response: type: array items: type: object status: type: integer /list-executions: get: summary: List executions description: List workflow execution history with optional filters and pagination tags: - Agent Builder parameters: - name: workflow_id in: query schema: type: integer description: Filter by workflow ID - name: status in: query schema: type: string description: Filter by execution status - name: limit in: query schema: type: integer default: 20 maximum: 100 - name: offset in: query schema: type: integer default: 0 responses: '200': description: Executions listed post: summary: List executions (POST) description: List workflow execution history tags: - Agent Builder requestBody: content: application/json: schema: type: object properties: workflow_id: type: integer status: type: string limit: type: integer default: 20 maximum: 100 offset: type: integer default: 0 responses: '200': description: Executions listed /get-execution-details: get: summary: Get execution details description: Get execution details with node logs tags: - Agent Builder requestBody: required: true content: application/json: schema: type: object required: - execution_id properties: execution_id: type: integer responses: '200': description: Execution details retrieved '404': description: Execution not found post: summary: Get execution details (POST) description: Get execution details with node logs tags: - Agent Builder requestBody: required: true content: application/json: schema: type: object required: - execution_id properties: execution_id: type: integer responses: '200': description: Execution details retrieved '404': description: Execution not found /update-workflow-metadata: put: summary: Update workflow metadata description: Update workflow metadata (name, description, publish status, visibility). Does NOT update DSL - use /save-workflow-version for that. tags: - Agent Builder requestBody: required: true content: application/json: schema: type: object required: - workflow_id properties: workflow_id: type: integer name: type: string maxLength: 255 description: type: string maxLength: 1000 is_published: type: boolean visibility: type: string enum: - private - org - team changelog: type: string maxLength: 1000 responses: '200': description: Workflow metadata updated '404': description: Workflow not found '409': description: Duplicate name post: summary: Update workflow metadata (POST) description: Update workflow metadata tags: - Agent Builder requestBody: required: true content: application/json: schema: type: object required: - workflow_id properties: workflow_id: type: integer name: type: string maxLength: 255 description: type: string maxLength: 1000 is_published: type: boolean visibility: type: string enum: - private - org - team changelog: type: string maxLength: 1000 responses: '200': description: Workflow metadata updated components: 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.