Agents API

Endpoints

Method	Path	Request	Response
GET	/api/agents	AgentListQuery	AgentList
GET	/api/agents/{agentId}	agentId: UUID	AgentEnvelope

List agents

GET /api/agents

Returns agents visible to the API-key owner.

Query parameters

Parameter	Type	Required	Constraints
includeSystem	"true" | "false"	No	Defaults to false
organizationId	string	No	UUID

Request

curl "https://app.dexto.ai/api/agents?includeSystem=true" \
  -H "Authorization: Bearer $DEXTO_API_KEY"

Response

{
    "agents": [
        {
            "id": "72ac5f10-5b5e-41e3-bdac-12eabfb84019",
            "name": "Research agent",
            "description": "Finds and synthesizes sources.",
            "avatarPreset": "round-teal-none-none",
            "isSystem": false,
            "canEdit": true,
            "desktopId": null,
            "greeting": { "kind": "text", "text": "What should I research?" },
            "llm": { "provider": "openai", "model": "gpt-5-mini" },
            "modelRoutingSelection": { "type": "platform" },
            "skillAccess": { "mode": "general" },
            "starterPrompts": [],
            "createdAt": "2026-09-12T12:00:00.000Z",
            "updatedAt": "2026-09-12T12:00:00.000Z"
        }
    ]
}

Returns

Field	JSON type	Required	Description
agents	array<Agent>	Yes	Owner-visible agents

Get agent

GET /api/agents/{agentId}

Returns one owner-visible agent by UUID.

Path parameters

Parameter	Type	Required	Description
agentId	string	Yes	Agent UUID

Request

curl https://app.dexto.ai/api/agents/72ac5f10-5b5e-41e3-bdac-12eabfb84019 \
  -H "Authorization: Bearer $DEXTO_API_KEY"

Response

{
    "agent": {
        "id": "72ac5f10-5b5e-41e3-bdac-12eabfb84019",
        "name": "Research agent",
        "description": "Finds and synthesizes sources.",
        "avatarPreset": "round-teal-none-none",
        "isSystem": false,
        "canEdit": true,
        "desktopId": null,
        "greeting": { "kind": "text", "text": "What should I research?" },
        "llm": { "provider": "openai", "model": "gpt-5-mini" },
        "modelRoutingSelection": { "type": "platform" },
        "permissions": {},
        "skillAccess": { "mode": "general" },
        "starterPrompts": [],
        "systemPrompt": "You are a research agent.",
        "duplicateSystemPrompt": null,
        "createdAt": "2026-09-12T12:00:00.000Z",
        "updatedAt": "2026-09-12T12:00:00.000Z"
    }
}

Returns

Field	JSON type	Required	Description
agent	Agent	Yes	Requested agent

Agent object

An Agent is an owner-visible runtime configuration. List responses return a reduced form; detail responses include permissions and prompt configuration.

{
    "id": "72ac5f10-5b5e-41e3-bdac-12eabfb84019",
    "name": "Research agent",
    "description": "Finds and synthesizes sources.",
    "avatarPreset": "round-teal-none-none",
    "isSystem": false,
    "canEdit": true,
    "desktopId": null,
    "greeting": { "kind": "text", "text": "What should I research?" },
    "llm": { "provider": "openai", "model": "gpt-5-mini" },
    "modelRoutingSelection": { "type": "platform" },
    "skillAccess": { "mode": "general" },
    "starterPrompts": [],
    "createdAt": "2026-09-12T12:00:00.000Z",
    "updatedAt": "2026-09-12T12:00:00.000Z"
}

Attributes

Field Type Description

id required

string

Agent UUID.

name required

string

Display name.

description required

string nullable

Agent description.

avatarPreset required

string

Sprite id formatted shape-color-hat-eyewear, for example round-teal-none-none. Shape: round, tall, square, wide, triangle, hexagon, cloud, drop, wing. Color: teal, white, brown, red, orange, amber, green, blue, violet, pink, gray. Hat: none, cap, beanie, crown, party, halo. Eyewear: none, glasses, shades, monocle, visor.

isSystem required

boolean

Whether Dexto owns the agent definition.

canEdit required

boolean

Whether the authenticated owner can edit the agent.

desktopId required

string nullable

Attached desktop UUID.

greeting required

AgentGreeting nullable

Initial greeting configuration.

Show child attributes

kind required

string

text or conversation.

text required

string

Greeting text.

messages conversation

array<object>

Conversation greeting messages.

replies conversation

array<object>

Suggested reply labels and prompts.

llm required

AgentLlm

Model configuration.

Show child attributes

provider required

string

anthropic, cursor, google, hosted, openai, openrouter, or xai.

model required

string

Provider model identifier.

maxInputTokens optional

integer

Positive input-token limit.

maxOutputTokens optional

integer

Positive output-token limit.

temperature optional

number

Value from 0 to 1.

reasoning optional

object

Reasoning variant and optional token budget.

modelRoutingSelection required

object nullable

Model credential routing.

Show child attributes

type required

string

platform, provider_method, or hosted_model_service.

providerId provider_method

string

Provider connection identifier.

methodId provider_method

string

Provider method identifier.

permissions detail only

object

Runtime permission configuration.

skillAccess required

object

Skill visibility policy.

Show child attributes

mode required

string

general or restricted.

selectedSkillIds optional

array<string>

Selected skill UUIDs; required in restricted mode.

starterPrompts required

array<object>

Suggested starting tasks.

systemPrompt detail only

string | object

Agent system-prompt configuration.

duplicateSystemPrompt detail only

string nullable

Alternate prompt exposed for duplicating a system agent.

createdAt required

string

ISO 8601 timestamp.

updatedAt required

string

ISO 8601 timestamp.