Ask Sage Agent Builder API
Agent builder workflow and agent management
OpenAPI Specification
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.