Capabilities API

Capability REST endpoints, requests, and responses.

Endpoints

Method	Path	Request	Response
`GET`	`/api/capabilities/sources`	`PaginationQuery`	`CapabilitySourceList`
`GET`	`/api/capabilities/search`	`CapabilitySearchQuery`	`CapabilitySearchResult`
`POST`	`/api/capabilities/describe`	`CapabilityDescribeRequest`	`CapabilityDescribeResult`
`POST`	`/api/capabilities/call`	`CapabilityCallRequest`	`CapabilityCallResult`

List sources

GET /api/capabilities/sources

Query parameters

Parameter	Type	Required	Constraints
`limit`	`integer`	No	`1–100`; default `20`
`offset`	`integer`	No	Minimum `0`; default `0`

Request
Response

curl "https://app.dexto.ai/api/capabilities/sources?limit=20&offset=0" \
  -H "Authorization: Bearer $DEXTO_API_KEY"

{
    "sources": [
        {
            "id": "dexto.platform",
            "kind": "platform",
            "title": "Dexto platform",
            "toolCount": 18
        }
    ]
}

Returns

Field	JSON type	Required	Description
`sources`	`array<CapabilitySource>`	Yes	Sources visible to the authenticated owner
`sources[].id`	`string`	Yes	Stable source identifier
`sources[].kind`	`string`	Yes	`app`, `connection`, `llm`, `mcp`, `platform`, `skill`, or `workspace`
`sources[].title`	`string`	Yes	Display title
`sources[].toolCount`	`integer`	No	Number of tools currently exposed by the source

Search capabilities

GET /api/capabilities/search

Query parameters

Parameter	Type	Required	Constraints
`q`	`string`	Yes	Non-empty after trimming
`limit`	`integer`	No	`1–100`; default `20`
`offset`	`integer`	No	Minimum `0`; default `0`

Request
Response

curl "https://app.dexto.ai/api/capabilities/search?q=search%20the%20web&limit=10" \
  -H "Authorization: Bearer $DEXTO_API_KEY"

{
    "items": [
        {
            "id": { "sourceId": "dexto.platform", "toolId": "web_search" },
            "sourceId": "dexto.platform",
            "name": "Web search",
            "description": "Search the public web.",
            "aliases": ["dexto.platform.web_search"],
            "tags": ["search", "web"],
            "execution": { "mode": "hosted", "owner": "cloud" },
            "invocable": { "mode": "available" }
        }
    ],
    "total": 1,
    "hasMore": false,
    "nextOffset": null
}

Returns

Field	JSON type	Required	Nullable	Description
`items`	`array<CapabilityTool>`	Yes	No	Matching capabilities
`total`	`integer`	Yes	No	Total matches before pagination
`hasMore`	`boolean`	Yes	No	Whether another page exists
`nextOffset`	`integer`	Yes	Yes	Offset for the next page

Describe capability

POST /api/capabilities/describe

Body parameters

Field	JSON type	Required	Constraints
`path`	`string`	Yes	Dotted capability alias such as `dexto.platform.web_search`

Request
Response

curl https://app.dexto.ai/api/capabilities/describe \
  -H "Authorization: Bearer $DEXTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "path": "dexto.platform.web_search" }'

{
    "found": true,
    "tool": {
        "id": { "sourceId": "dexto.platform", "toolId": "web_search" },
        "sourceId": "dexto.platform",
        "name": "Web search",
        "description": "Search the public web.",
        "aliases": ["dexto.platform.web_search"],
        "tags": ["search", "web"],
        "inputSchema": {
            "type": "object",
            "properties": { "query": { "type": "string" } },
            "required": ["query"]
        },
        "execution": { "mode": "hosted", "owner": "cloud" },
        "invocable": { "mode": "available" },
        "examples": [{ "label": "Search the web", "input": { "query": "Dexto agent platform" } }]
    }
}

Returns

Field	JSON type	Required	Description
`found`	`boolean`	Yes	Whether the alias resolved
`path`	`string`	When `found` is `false`	Requested alias
`tool`	`CapabilityToolDescription`	When `found` is `true`	Capability metadata and schemas

Call capability

POST /api/capabilities/call

Body parameters

Field	JSON type	Required	Constraints
`path`	`string`	One of `path` or `id`	Dotted capability alias
`id`	`CapabilityId`	One of `path` or `id`	Structured capability identifier
`input`	`any JSON value`	No	Defaults to `{}`; validated against the capability input schema
`idempotencyKey`	`string`	No	Non-empty caller-defined operation key

curl https://app.dexto.ai/api/capabilities/call \
  -H "Authorization: Bearer $DEXTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "dexto.platform.web_search",
    "input": { "query": "Dexto agent platform" },
    "idempotencyKey": "search-dexto-2026-09-12"
  }'

curl https://app.dexto.ai/api/capabilities/call \
  -H "Authorization: Bearer $DEXTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": { "sourceId": "dexto.platform", "toolId": "web_search" },
    "input": { "query": "Dexto agent platform" }
  }'

{
    "ok": true,
    "data": {
        "results": [{ "title": "Dexto", "url": "https://www.dexto.ai", "snippet": "..." }]
    },
    "receipt": {
        "capabilityId": { "sourceId": "dexto.platform", "toolId": "web_search" },
        "finishedAt": "2026-09-12T12:00:01.000Z",
        "invocationId": "inv_01K4M6V7P8",
        "sourceId": "dexto.platform",
        "status": "completed"
    }
}

Returns

Field	JSON type	Required	Description
`ok`	`boolean`	Yes	Discriminator for success or failure
`data`	`any JSON value`	When `ok` is `true`	Capability-specific output
`error`	`CapabilityError`	When `ok` is `false`	Structured invocation failure
`receipt`	`CapabilityReceipt`	Success: yes; failure: no	Execution receipt when invocation began

Capability objects

A Capability describes an operation exposed by a platform, connection, app, skill, model, or workspace source.

{
    "id": { "sourceId": "dexto.platform", "toolId": "web_search" },
    "sourceId": "dexto.platform",
    "name": "Web search",
    "description": "Search the public web.",
    "aliases": ["dexto.platform.web_search"],
    "tags": ["search", "web"],
    "execution": { "mode": "hosted", "owner": "cloud" },
    "invocable": { "mode": "available" }
}

{
    "capabilityId": { "sourceId": "dexto.platform", "toolId": "web_search" },
    "finishedAt": "2026-09-12T12:00:01.000Z",
    "invocationId": "inv_01K4M6V7P8",
    "sourceId": "dexto.platform",
    "status": "completed"
}

{
    "code": "validation_failed",
    "message": "Capability input did not match its schema.",
    "details": { "issues": [] }
}

CapabilityTool

id required

CapabilityId

Structured identifier.

Show child attributes

sourceId required

string

Capability source identifier.

toolId required

string

Tool identifier within the source.

resourceId optional

string

Source-specific resource identifier.

version optional

string

Source-specific capability version.

sourceId required

string

Capability source identifier.

name required

string

Display name.

description required

string

Human-readable operation description.

aliases required

array<string>

Dotted invocation aliases.

tags required

array<string>

Search terms.

inputSchema optional

object

JSON Schema for invocation input.

outputSchema optional

object

JSON Schema for successful output.

execution required

CapabilityExecution

Execution location and owner.

Show child attributes

mode required

string

hosted, workspace, remote_mcp, llm_gateway, or instruction_only.

owner hosted/workspace

string

cloud or runtime.

connectionId remote_mcp

string

Remote MCP connection identifier.

provider llm_gateway

string

Gateway provider identifier.

invocable required

CapabilityInvocability

Current invocation availability.

Show child attributes

mode required

string

available, describe_only, or planned.

reason not available

string

Why invocation is unavailable.

CapabilityToolDescription

Includes every CapabilityTool field plus:

examples optional

array<object>

Example labels and inputs.

inputTypeScript optional

string

Source-provided display definition.

outputTypeScript optional

string

Source-provided display definition.

typeScriptDefinitions optional

object<string, string>

Named source-provided display definitions.

usageNotes optional

array<string>

Invocation guidance.

CapabilityReceipt

capabilityId required

CapabilityId

Invoked capability.

finishedAt required

string

ISO 8601 completion timestamp.

invocationId required

string

Server-generated invocation identifier.

sourceId required

string

Executing source.

status required

string

blocked or completed.

CapabilityError

code required

string

approval_required, approval_denied, not_found, timeout, tool_error, or validation_failed.

message required

string

Human-readable failure description.

approvalKey approval_required

string nullable

Approval request key when available.

approval optional

object

Approval metadata.

details validation_failed

object

Validation issues containing code, message, and path.