Skip to main content
API docs by Redocly

Dexto API (1.2.4)

Download OpenAPI specification:Download

OpenAPI spec for the Dexto REST API server

system

System health and status endpoints

Health Check

Returns server health status

Responses

config

Agent configuration and greeting management

Get Greeting Message

Retrieves the greeting message from the agent configuration

query Parameters
sessionId
string

Session identifier to retrieve session-specific greeting

Responses

Response samples

Content type
application/json
{
  • "greeting": "string"
}

messages

Send messages to the agent and manage conversations

Send Message (async)

Sends a message and returns immediately. The full response will be sent over WebSocket

Request Body schema: application/json
message
string

The user message text

sessionId
string

The session to use for this message

stream
boolean

Set to true to receive streaming chunks over WebSocket

object

Optional image data to include with the message

object

Optional file data to include with the message

Responses

Request samples

Content type
application/json
{
  • "message": "string",
  • "sessionId": "string",
  • "stream": true,
  • "imageData": {
    },
  • "fileData": {
    }
}

Response samples

Content type
application/json
{
  • "response": "string",
  • "sessionId": "string"
}

Send Message (sync)

Sends a message and waits for the full response

Request Body schema: application/json
message
string

The user message text

sessionId
string

The session to use for this message

stream
boolean

Set to true to receive streaming chunks over WebSocket

object

Optional image data to include with the message

object

Optional file data to include with the message

Responses

Request samples

Content type
application/json
{
  • "message": "string",
  • "sessionId": "string",
  • "stream": true,
  • "imageData": {
    },
  • "fileData": {
    }
}

Response samples

Content type
application/json
{
  • "response": "string",
  • "sessionId": "string"
}

Reset Conversation

Resets the conversation history for a given session

Request Body schema: application/json
sessionId
string

The ID of the session to reset

Responses

Request samples

Content type
application/json
{
  • "sessionId": "string"
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "sessionId": "string"
}

sessions

Create and manage conversation sessions

List Sessions

Retrieves a list of all active sessions

Responses

Response samples

Content type
application/json
{
  • "sessions": [
    ]
}

Create Session

Creates a new session

Request Body schema: application/json
sessionId
string

A custom ID for the new session

Responses

Request samples

Content type
application/json
{
  • "sessionId": "string"
}

Response samples

Content type
application/json
{
  • "session": {
    }
}

Get Current Session

Retrieves the ID of the currently active session

Responses

Response samples

Content type
application/json
{
  • "currentSessionId": "string"
}

Get Session Details

Fetches details for a specific session

path Parameters
sessionId
required
string

Session identifier

Responses

Response samples

Content type
application/json
{
  • "session": {
    }
}

Delete Session

Permanently deletes a session and all its conversation history. This action cannot be undone

path Parameters
sessionId
required
string

Session identifier

Responses

Response samples

Content type
application/json
{
  • "status": "deleted",
  • "sessionId": "string"
}

Update Session Title

Updates the title of an existing session

path Parameters
sessionId
required
string

Session identifier

Request Body schema: application/json
title
required
string [ 1 .. 120 ] characters

New title for the session (maximum 120 characters)

Responses

Request samples

Content type
application/json
{
  • "title": "string"
}

Response samples

Content type
application/json
{
  • "session": {
    }
}

Get Session History

Retrieves the conversation history for a session

path Parameters
sessionId
required
string

Session identifier

Responses

Response samples

Content type
application/json
{
  • "history": [
    ]
}

Cancel Session Run

Cancels an in-flight agent run for the specified session

path Parameters
sessionId
required
string

Session identifier

Responses

Response samples

Content type
application/json
{
  • "cancelled": true,
  • "sessionId": "string"
}

Load Session

Sets a session as the current active session

path Parameters
sessionId
required
string

Session identifier

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "status": "loaded",
  • "sessionId": "string",
  • "currentSession": "string"
}

llm

Configure and switch between LLM providers and models

Get Current LLM Config

Retrieves the current LLM configuration for the agent or a specific session

query Parameters
sessionId
string

Session identifier to retrieve session-specific LLM configuration

Responses

Response samples

Content type
application/json
{
  • "config": {
    }
}

LLM Catalog

Providers, models, capabilities, and API key status

query Parameters
string or Array of strings

Comma-separated list of LLM providers to filter by

string or string or string or string

Filter by API key presence (true or false)

router
string
Enum: "vercel" "in-built"

Filter by router type (vercel or in-built)

fileType
string
Enum: "pdf" "image" "audio"

Filter by supported file type (audio, pdf, or image)

string or string or string or string

Include only default models (true or false)

mode
string
Default: "grouped"
Enum: "grouped" "flat"

Response format mode (grouped by provider or flat list)

Responses

Response samples

Content type
application/json
{
  • "models": [
    ]
}

Save Provider API Key

Stores an API key for a provider in .env and makes it available immediately

Request Body schema: application/json
provider
required
string
Enum: "openai" "openai-compatible" "anthropic" "google" "groq" "xai" "cohere"

LLM provider identifier (e.g., openai, anthropic)

apiKey
required
string non-empty

API key for the provider

Responses

Request samples

Content type
application/json
{
  • "provider": "openai",
  • "apiKey": "string"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "provider": "openai",
  • "envVar": "string"
}

Switch LLM

Switches the LLM configuration for the agent or a specific session

Request Body schema: application/json
sessionId
string

Session identifier for session-specific LLM configuration

provider
string
Enum: "openai" "openai-compatible" "anthropic" "google" "groq" "xai" "cohere"

LLM provider (e.g., 'openai', 'anthropic', 'google', 'groq')

model
string

Specific model name for the selected provider

apiKey
string

API key for provider; can be given directly or via $ENV reference

maxIterations
integer > 0

Max iterations for agentic loops

router
string
Enum: "vercel" "in-built"

Router to use (vercel | in-built)

baseURL
string

Base URL for provider (e.g., https://api.openai.com/v1). Only certain providers support this.

maxInputTokens
integer > 0

Max input tokens for history; required for unknown models

maxOutputTokens
integer > 0

Max tokens for model output

temperature
number or null [ 0 .. 1 ]

Randomness: 0 deterministic, 1 creative

allowedMediaTypes
Array of strings

MIME type patterns for media expansion (e.g., "image/*", "application/pdf"). If omitted, uses model capabilities from registry. Supports wildcards.

Responses

Request samples

Content type
application/json
{
  • "sessionId": "string",
  • "provider": "openai",
  • "model": "string",
  • "apiKey": "string",
  • "maxIterations": 0,
  • "router": "vercel",
  • "baseURL": "string",
  • "maxInputTokens": 0,
  • "maxOutputTokens": 0,
  • "temperature": 1,
  • "allowedMediaTypes": [
    ]
}

Response samples

Content type
application/json
{
  • "config": {
    },
  • "sessionId": "string"
}

mcp

Manage Model Context Protocol (MCP) servers and tools

Add MCP Server

Connects a new MCP server dynamically

Request Body schema: application/json
name
required
string non-empty

A unique name for the server

required
object or object or object

The server configuration object

persistToAgent
boolean

If true, saves the server to agent configuration file

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "config": {
    },
  • "persistToAgent": true
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "name": "string"
}

List MCP Servers

Gets a list of all connected and failed MCP servers

Responses

Response samples

Content type
application/json
{
  • "servers": [
    ]
}

List Server Tools

Retrieves the list of tools available on a specific MCP server

path Parameters
serverId
required
string

The ID of the MCP server

Responses

Response samples

Content type
application/json
{
  • "tools": [
    ]
}

Remove MCP Server

Disconnects and removes an MCP server

path Parameters
serverId
required
string

The ID of the MCP server

Responses

Response samples

Content type
application/json
{
  • "status": "disconnected",
  • "id": "string"
}

Restart MCP Server

Restarts a connected MCP server

path Parameters
serverId
required
string

The ID of the MCP server

Responses

Response samples

Content type
application/json
{
  • "status": "restarted",
  • "id": "string"
}

Execute MCP Tool

Executes a tool on an MCP server directly

path Parameters
serverId
required
string

The ID of the MCP server

toolName
required
string

The name of the tool to execute

Request Body schema: application/json
property name*
additional property
any or null

Responses

Request samples

Content type
application/json
{
  • "property1": null,
  • "property2": null
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": null,
  • "error": "string"
}

List Server Resources

Retrieves all resources available from a specific MCP server

path Parameters
serverId
required
string

The ID of the MCP server

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "resources": [
    ]
}

Read Server Resource Content

Reads content from a specific resource on an MCP server. This endpoint automatically constructs the qualified URI format (mcp:serverId:resourceId)

path Parameters
serverId
required
string

The ID of the MCP server

resourceId
required
string non-empty

The URI-encoded resource identifier on that server

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

webhooks

Register and manage webhook endpoints for agent events

Register Webhook

Registers a new webhook endpoint to receive agent events

Request Body schema: application/json
url
required
string <uri>

The URL to send webhook events to (must be a valid HTTP/HTTPS URL)

secret
string

A secret key for HMAC signature verification

description
string

A description of the webhook for reference

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "webhook": {}
}

List Webhooks

Retrieves a list of all registered webhooks

Responses

Response samples

Content type
application/json
{
  • "webhooks": [
    ]
}

Get Webhook Details

Fetches details for a specific webhook

path Parameters
webhookId
required
string

The webhook identifier

Responses

Response samples

Content type
application/json
{
  • "webhook": {}
}

Delete Webhook

Permanently removes a webhook endpoint. This action cannot be undone

path Parameters
webhookId
required
string

The webhook identifier

Responses

Response samples

Content type
application/json
{
  • "status": "removed",
  • "webhookId": "string"
}

Test Webhook

Sends a sample event to test webhook connectivity and configuration

path Parameters
webhookId
required
string

The webhook identifier

Responses

Response samples

Content type
application/json
{
  • "test": "completed",
  • "result": {
    }
}

search

Search through messages and sessions

Search Messages

Searches for messages across all sessions or within a specific session

query Parameters
q
required
string non-empty

Search query string

limit
number [ 1 .. 100 ]

Maximum number of results to return (default: 20)

offset
number or null >= 0

Number of results to skip for pagination (default: 0)

sessionId
string

Limit search to a specific session

role
string
Enum: "user" "assistant" "system" "tool"

Filter by message role

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "total": 0,
  • "hasMore": true,
  • "query": "string"
}

Search Sessions

Searches for sessions that contain the specified query

query Parameters
q
required
string non-empty

Search query string

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "total": 0,
  • "hasMore": true,
  • "query": "string"
}

memory

Store and retrieve agent memories for context

Create Memory

Creates a new memory

Request Body schema: application/json
content
required
string [ 1 .. 10000 ] characters

The memory content

tags
Array of strings <= 10 items [ items [ 1 .. 50 ] characters ]

Optional tags

object

Optional metadata

Responses

Request samples

Content type
application/json
{
  • "content": "string",
  • "tags": [
    ],
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "memory": {
    }
}

List Memories

Retrieves a list of all memories with optional filtering

query Parameters
tags
string

Comma-separated list of tags to filter by

source
string
Enum: "user" "system"

Filter by source (user or system)

pinned
string

Filter by pinned status (true or false)

limit
string

Maximum number of memories to return

offset
string

Number of memories to skip

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "memories": [
    ]
}

Get Memory by ID

Retrieves a specific memory by its unique identifier

path Parameters
id
required
string non-empty

Memory unique identifier

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "memory": {
    }
}

Update Memory

Updates an existing memory. Only provided fields will be updated

path Parameters
id
required
string non-empty

Memory unique identifier

Request Body schema: application/json
content
string [ 1 .. 10000 ] characters

Updated content

tags
Array of strings <= 10 items [ items [ 1 .. 50 ] characters ]

Updated tags (replaces existing)

object

Updated metadata (merges with existing)

Responses

Request samples

Content type
application/json
{
  • "content": "string",
  • "tags": [
    ],
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "memory": {
    }
}

Delete Memory

Permanently deletes a memory. This action cannot be undone

path Parameters
id
required
string non-empty

Memory unique identifier

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "message": "string"
}

prompts

Manage custom prompts and templates

List Prompts

Retrieves all available prompts, including both built-in and custom prompts

Responses

Response samples

Content type
application/json
{
  • "prompts": [
    ]
}

Create Custom Prompt

Creates a new custom prompt with optional resource attachment. Maximum request size: 10MB

Request Body schema: application/json
name
required
string non-empty

Unique name for the custom prompt

title
string

Display title for the prompt

description
string

Description of what the prompt does

content
required
string non-empty

The prompt content text (can include {{argumentName}} placeholders)

Array of objects

Array of argument definitions

object

Attach a resource to this prompt

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "title": "string",
  • "description": "string",
  • "content": "string",
  • "arguments": [
    ],
  • "resource": {
    }
}

Response samples

Content type
application/json
{
  • "prompt": {
    }
}

Delete Custom Prompt

Permanently deletes a custom prompt. Built-in prompts cannot be deleted

path Parameters
name
required
string non-empty

The prompt name

Responses

Get Prompt Definition

Fetches the definition for a specific prompt

path Parameters
name
required
string non-empty

The prompt name

Responses

Response samples

Content type
application/json
{
  • "definition": {
    }
}

Resolve Prompt

Resolves a prompt template with provided arguments and returns the final text with resources

path Parameters
name
required
string non-empty

The prompt name

query Parameters
context
string

Additional context for prompt resolution

args
string

Arguments to substitute in the prompt template (pass as a JSON string)

Responses

Response samples

Content type
application/json
{
  • "text": "string",
  • "resources": [
    ]
}

resources

Access and manage resources from MCP servers and internal providers

List All Resources

Retrieves a list of all available resources from all sources (MCP servers and internal providers)

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "resources": [
    ]
}

Read Resource Content

Reads the content of a specific resource by its URI. The resource ID in the URL must be URI-encoded

path Parameters
resourceId
required
string non-empty

The URI-encoded resource identifier

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "content": {
    }
}

Check Resource Exists

Checks if a resource exists by its URI without retrieving its content

path Parameters
resourceId
required
string non-empty

The URI-encoded resource identifier

Responses

agent

Current agent configuration and file operations

Get Agent File Path

Retrieves the file path of the currently active agent configuration

Responses

Response samples

Content type
application/json
{
  • "path": "string",
  • "relativePath": "string",
  • "name": "string",
  • "isDefault": true
}

Get Agent Configuration

Retrieves the raw YAML configuration of the currently active agent

Responses

Response samples

Content type
application/json
{
  • "yaml": "string",
  • "path": "string",
  • "relativePath": "string",
  • "lastModified": "string",
  • "warnings": [
    ]
}

Save Agent Configuration

Saves and applies YAML agent configuration. Creates backup before saving

Request Body schema: application/json
yaml
required
string non-empty

YAML agent configuration content to save

Responses

Request samples

Content type
application/json
{
  • "yaml": "string"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "path": "string",
  • "reloaded": true,
  • "restarted": true,
  • "changesApplied": [
    ],
  • "message": "string"
}

Validate Agent Configuration

Validates YAML agent configuration without saving it

Request Body schema: application/json
yaml
required
string non-empty

YAML agent configuration content to validate

Responses

Request samples

Content type
application/json
{
  • "yaml": "string"
}

Response samples

Content type
application/json
{
  • "valid": true,
  • "errors": [
    ],
  • "warnings": [
    ]
}

Export Agent Configuration

Exports the effective agent configuration with sensitive values redacted

query Parameters
sessionId
string

Session identifier to export session-specific configuration

Responses

agents

Install, switch, and manage agent configurations

List Agents

Retrieves all agents (installed, available, and current active agent)

Responses

Response samples

Content type
application/json
{
  • "installed": [
    ],
  • "available": [
    ],
  • "current": {
    }
}

Get Current Agent

Retrieves the currently active agent

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string"
}

Install Agent

Installs an agent from the registry or from a custom source

Request Body schema: application/json
Any of
id
required
string non-empty

Unique agent identifier

name
string

Display name (defaults to derived from id)

sourcePath
required
string non-empty

Path to agent configuration file or directory

required
object

Agent metadata including description, author, and tags

injectPreferences
boolean
Default: true

Whether to inject user preferences into agent config

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "path": "string"
}

Response samples

Content type
application/json
{
  • "installed": true,
  • "id": "string",
  • "name": "string",
  • "type": "builtin"
}

Switch Agent

Switches to a different agent by ID or file path

Request Body schema: application/json
id
required
string non-empty

Unique agent identifier (e.g., "database-agent")

path
string

Optional absolute file path for file-based agents (e.g., "/path/to/agent.yml")

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "path": "string"
}

Response samples

Content type
application/json
{
  • "switched": true,
  • "id": "string",
  • "name": "string"
}

Validate Agent Name

Checks if an agent ID conflicts with existing agents

Request Body schema: application/json
id
required
string non-empty

Unique agent identifier (e.g., "database-agent")

path
string

Optional absolute file path for file-based agents (e.g., "/path/to/agent.yml")

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "path": "string"
}

Response samples

Content type
application/json
{
  • "valid": true,
  • "conflict": "string",
  • "message": "string"
}

Uninstall Agent

Removes an agent from the system. Custom agents are removed from registry; builtin agents can be reinstalled

Request Body schema: application/json
id
required
string non-empty

Unique agent identifier to uninstall

force
boolean
Default: false

Force uninstall even if agent is currently active

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "force": false
}

Response samples

Content type
application/json
{
  • "uninstalled": true,
  • "id": "string"
}

Create Custom Agent

Creates a new custom agent from scratch via the UI/API

Request Body schema: application/json
id
required
string non-empty ^[a-z0-9-]+$

Unique agent identifier

name
required
string non-empty

Display name for the agent

description
required
string non-empty

One-line description of the agent

author
string

Author or organization

tags
Array of strings
Default: []

Tags for discovery

required
object

LLM configuration

systemPrompt
required
string non-empty

System prompt for the agent

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "author": "string",
  • "tags": [ ],
  • "llm": {
    },
  • "systemPrompt": "string"
}

Response samples

Content type
application/json
{
  • "created": true,
  • "id": "string",
  • "name": "string"
}