Skip to main content
API docs by Redocly

Dexto API (1.5.7)

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 SSE

Request Body schema: application/json
required
string or (Array of objects or objects or objects)

Message content - string for text, or ContentPart[] for multimodal

sessionId
required
string non-empty

The session to use for this message

Responses

Request samples

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

Response samples

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

Send Message (sync)

Sends a message and waits for the full response

Request Body schema: application/json
required
string or (Array of objects or objects or objects)

Message content - string for text, or ContentPart[] for multimodal

sessionId
required
string non-empty

The session to use for this message

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "response": "string",
  • "sessionId": "string",
  • "tokenUsage": {
    },
  • "reasoning": "string",
  • "model": "string",
  • "provider": "openai"
}

Reset Conversation

Resets the conversation history for a given session

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

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"
}

Stream message response

Sends a message and streams the response via Server-Sent Events (SSE). Returns SSE stream directly in response. Events include llm:thinking, llm:chunk, llm:tool-call, llm:tool-result, llm:response, and llm:error. If the session is busy processing another message, returns 202 with queue information.

Request Body schema: application/json
required
string or (Array of objects or objects or objects)

Message content - string for text, or ContentPart[] for multimodal

sessionId
required
string non-empty

The session to use for this message

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "busy": true,
  • "sessionId": "string",
  • "queueLength": 0,
  • "hint": "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 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 along with processing status

path Parameters
sessionId
required
string

Session identifier

Responses

Response samples

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

Cancel Session Run

Cancels an in-flight agent run for the specified session. By default (soft cancel), only the current LLM call is cancelled and queued messages continue processing. Set clearQueue=true for hard cancel to also clear any queued messages.

path Parameters
sessionId
required
string

Session identifier

Request Body schema: application/json
optional
clearQueue
boolean
Default: false

If true (hard cancel), clears queued messages. If false (soft cancel, default), queued messages continue processing.

Responses

Request samples

Content type
application/json
{
  • "clearQueue": false
}

Response samples

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

Load Session

Validates and retrieves session information including processing status. The client should track the active session.

path Parameters
sessionId
required
string

Session identifier

Responses

Response samples

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

Generate Session Title

Generates a descriptive title for the session using the first user message. Returns existing title if already set.

path Parameters
sessionId
required
string

Session identifier

Responses

Response samples

Content type
application/json
{
  • "title": "string",
  • "sessionId": "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": {
    },
  • "routing": {
    }
}

LLM Catalog

Providers, models, capabilities, and API key status

query Parameters
scope
string
Default: "all"
Enum: "curated" "all"

Catalog scope: 'curated' returns a small, UI-friendly set of models; 'all' returns the full registry (can be large)

string or Array of strings

Comma-separated list of LLM providers to filter by

string or string or string or string

Include models list in the response (true or false)

string or string or string or string

Filter by API key presence (true or false)

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": [
    ]
}

Switch LLM

Switches the LLM configuration for the agent or a specific session

Request Body schema: application/json
provider
string
Enum: "openai" "openai-compatible" "anthropic" "google" "groq" "xai" "cohere" "minimax" "glm" "openrouter" "litellm" "glama" "vertex" "bedrock" "local" "ollama" "dexto"

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

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.

reasoningEffort
string
Enum: "none" "minimal" "low" "medium" "high" "xhigh"

OpenAI reasoning effort level for reasoning models (o1, o3, codex). Options: 'none', 'minimal', 'low', 'medium' (recommended), 'high', 'xhigh'

sessionId
string

Session identifier for session-specific LLM configuration

Responses

Request samples

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

Response samples

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

List Custom Models

Returns all saved custom openai-compatible model configurations

Responses

Response samples

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

Create Custom Model

Saves a new custom openai-compatible model configuration

Request Body schema: application/json
name
required
string non-empty
provider
string
Default: "openai-compatible"
Enum: "openai-compatible" "openrouter" "litellm" "glama" "bedrock" "ollama" "local" "vertex" "dexto"
baseURL
string <uri>
displayName
string
maxInputTokens
integer > 0
maxOutputTokens
integer > 0
apiKey
string
filePath
string
reasoningEffort
string
Enum: "none" "minimal" "low" "medium" "high" "xhigh"

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "provider": "openai-compatible",
  • "baseURL": "http://example.com",
  • "displayName": "string",
  • "maxInputTokens": 0,
  • "maxOutputTokens": 0,
  • "apiKey": "string",
  • "filePath": "string",
  • "reasoningEffort": "none"
}

Response samples

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

Delete Custom Model

Deletes a custom model by name

path Parameters
name
required
string non-empty

Model name to delete

Responses

Response samples

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

Get Model Capabilities

Returns the capabilities (supported file types) for a specific provider/model combination. Handles gateway providers (dexto, openrouter) by resolving to the underlying model capabilities.

query Parameters
provider
required
string
Enum: "openai" "openai-compatible" "anthropic" "google" "groq" "xai" "cohere" "minimax" "glm" "openrouter" "litellm" "glama" "vertex" "bedrock" "local" "ollama" "dexto"

LLM provider name

model
required
string non-empty

Model name (supports both native and OpenRouter format)

Responses

Response samples

Content type
application/json
{
  • "provider": "openai",
  • "model": "string",
  • "supportedFileTypes": [
    ]
}

Get Provider API Key Status

Retrieves the API key status for a provider. Returns a masked key value (e.g., sk-proj...xyz4) for UI display purposes.

path Parameters
provider
required
string
Enum: "openai" "openai-compatible" "anthropic" "google" "groq" "xai" "cohere" "minimax" "glm" "openrouter" "litellm" "glama" "vertex" "bedrock" "local" "ollama" "dexto"

LLM provider identifier

Responses

Response samples

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

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" "minimax" "glm" "openrouter" "litellm" "glama" "vertex" "bedrock" "local" "ollama" "dexto"

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

apiKey
required
string non-empty

API key for the provider (writeOnly - never returned in responses)

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "ok": true,
  • "provider": "openai",
  • "envVar": "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

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

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

Complete agent configuration

Responses

Request samples

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

Response samples

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

queue

Manage message queue for busy sessions

Get queued messages

Returns all messages waiting in the queue for a session

path Parameters
sessionId
required
string non-empty

Session ID

Responses

Response samples

Content type
application/json
{
  • "messages": [
    ],
  • "count": 0
}

Queue a message

Adds a message to the queue for processing when the session is no longer busy

path Parameters
sessionId
required
string non-empty

Session ID

Request Body schema: application/json
required
string or (Array of objects or objects or objects)

Message content - string for text, or ContentPart[] for multimodal

kind
string
Enum: "default" "background"

Optional queued message kind

Responses

Request samples

Content type
application/json
{
  • "content": "string",
  • "kind": "default"
}

Response samples

Content type
application/json
{
  • "queued": true,
  • "id": "string",
  • "position": 0
}

Clear message queue

Removes all messages from the queue for a session

path Parameters
sessionId
required
string non-empty

Session ID

Responses

Response samples

Content type
application/json
{
  • "cleared": true,
  • "count": 0
}

Remove queued message

Removes a specific message from the queue

path Parameters
sessionId
required
string non-empty

Session ID

messageId
required
string non-empty

ID of the queued message to remove

Responses

Response samples

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

openrouter

OpenRouter model validation and cache management

Validate OpenRouter Model

Validates an OpenRouter model ID against the cached model registry. Refreshes cache if stale.

path Parameters
modelId
required
string non-empty

OpenRouter model ID to validate (e.g., anthropic/claude-3.5-sonnet)

Responses

Response samples

Content type
application/json
{
  • "valid": true,
  • "modelId": "string",
  • "status": "valid",
  • "error": "string",
  • "info": {
    }
}

Refresh OpenRouter Model Cache

Forces a refresh of the OpenRouter model registry cache from the API.

Responses

Response samples

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

discovery

Discover available providers and capabilities

Discover Available Providers and Tools

Returns all registered providers (blob storage, database, compaction, custom tools) and available internal tools. Useful for building UIs that need to display configurable options.

Responses

Response samples

Content type
application/json
{
  • "blob": [
    ],
  • "database": [
    ],
  • "compaction": [
    ],
  • "customTools": [
    ],
  • "internalTools": [
    ]
}

tools

List and inspect available tools from internal, custom, and MCP sources

List All Tools

Retrieves all available tools from all sources (internal, custom, and MCP servers)

Responses

Response samples

Content type
application/json
{
  • "tools": [
    ],
  • "totalCount": 0,
  • "internalCount": 0,
  • "customCount": 0,
  • "mcpCount": 0
}

models

List and manage local GGUF models and Ollama models

List Local Models

Returns all installed local GGUF models from ~/.dexto/models/state.json. These are models downloaded from HuggingFace or manually registered.

Responses

Response samples

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

List Ollama Models

Returns available models from the local Ollama server. Returns empty list with available=false if Ollama is not running.

query Parameters
baseURL
string <uri>

Ollama server URL (default: http://localhost:11434)

Responses

Response samples

Content type
application/json
{
  • "available": true,
  • "version": "string",
  • "models": [
    ],
  • "error": "string"
}

Validate GGUF File

Validates that a GGUF file exists and is readable. Used by Web UI to validate custom file paths before saving.

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

Absolute path to the GGUF file to validate

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "valid": true,
  • "sizeBytes": 0,
  • "error": "string"
}

Delete Installed Model

Removes an installed local model from state.json. Optionally deletes the GGUF file from disk (default: true).

path Parameters
modelId
required
string

The model ID to delete

Request Body schema: application/json
optional
deleteFile
boolean
Default: true

Whether to also delete the GGUF file from disk

Responses

Request samples

Content type
application/json
{
  • "deleteFile": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "modelId": "string",
  • "fileDeleted": true,
  • "error": "string"
}

auth

Dexto authentication status and management

Dexto Auth Status

Returns dexto authentication status. Used by Web UI to check if user can use dexto features.

Responses

Response samples

Content type
application/json
{
  • "enabled": true,
  • "authenticated": true,
  • "canUse": true
}

a2a

Send Message

Send a message to the agent (A2A message/send)

Request Body schema: application/json
required
object

Message to send to the agent

object

Optional configuration

object

Optional metadata

Responses

Request samples

Content type
application/json
{
  • "message": {
    },
  • "configuration": {
    },
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "contextId": "string",
  • "status": {
    },
  • "history": [
    ],
  • "artifacts": [
    ],
  • "metadata": {
    },
  • "kind": "task"
}

List Tasks

List all A2A tasks with optional filtering (A2A tasks/list)

query Parameters
contextId
string

Filter by context ID

status
string
Enum: "submitted" "working" "input-required" "completed" "canceled" "failed" "rejected" "auth-required" "unknown"

Filter by task state

pageSize
string

Number of results (1-100, default 50)

pageToken
string

Pagination token (not yet implemented - reserved for future use)

historyLength
string

Limit history items (not yet implemented - reserved for future use)

lastUpdatedAfter
string

Unix timestamp filter (not yet implemented - reserved for future use)

includeArtifacts
string

Include artifacts in response (not yet implemented - reserved for future use)

Responses

Response samples

Content type
application/json
{
  • "tasks": [
    ],
  • "totalSize": 0,
  • "pageSize": 0,
  • "nextPageToken": "string"
}

Get Task

Retrieve a specific task by ID (A2A tasks/get)

path Parameters
id
required
string

Task ID

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "contextId": "string",
  • "status": {
    },
  • "history": [
    ],
  • "artifacts": [
    ],
  • "metadata": {
    },
  • "kind": "task"
}

Cancel Task

Cancel a running task (A2A tasks/cancel)

path Parameters
id
required
string

Task ID

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "contextId": "string",
  • "status": {
    },
  • "history": [
    ],
  • "artifacts": [
    ],
  • "metadata": {
    },
  • "kind": "task"
}

approvals

Get Pending Approvals

Fetch all pending approval requests for a session. Use this to restore UI state after page refresh.

query Parameters
sessionId
required
string

The session ID to fetch pending approvals for

Responses

Response samples

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

Submit Approval Decision

Submit a user decision for a pending approval request

path Parameters
approvalId
required
string

The ID of the approval request

header Parameters
Idempotency-Key
string

Optional key to ensure idempotent processing

Request Body schema: application/json
status
required
string
Enum: "approved" "denied"

The user decision

object

Optional form data provided by the user (for elicitation)

rememberChoice
boolean

Whether to remember this choice for future requests

Responses

Request samples

Content type
application/json
{
  • "status": "approved",
  • "formData": {
    },
  • "rememberChoice": true
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "approvalId": "string",
  • "status": "approved"
}