Run a capability — returns a value, a questionnaire, or a proposal

Runs one capability from the catalogue. Three shapes of success, and a client has to handle all three:

value — the result, and the interaction is over.
input_required — a questionnaire to fill and send back through requestState. The handle is single-use.
proposal — a computed diff. Nothing has been written; applyProposal decides.

The project is never a parameter. It comes from the credential, and a scope key sent in params at any depth is refused with scope_in_params rather than ignored — silently dropping it would let a caller believe they had switched project.

A capability the catalogue marks writesOnInvoke has already done its work when this returns. Ask before calling one, not after.

POST/v1/capabilities/{capabilityId}/invoke

Authorization

agent-token

AuthorizationBearer <token>

An agent project token. Obtained by OAuth consent for an AI client, or derived per project from an organisation service key for a machine. A scoped API key authenticates the transport but opens no capability: a capability takes its project from the credential.

In: header

Path Parameters

capabilityId*string

The capability to run, exactly as GET /capabilities returns it. This surface does not resolve an approximate name: an unknown identifier is refused with capability_unknown, and the response carries a suggestions array — the cause is almost always a typo.

Match^[a-z][a-z0-9-]*(\.[a-z0-9-]+)+$

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

params?

Parameters for the capability, matching the JSON Schema that GET /v1/capabilities publishes for it under paramsSchema. The shape therefore differs per capability — read it there rather than guessing.

Omitting a required parameter is not always an error. Some capabilities answer with a questionnaire instead, so a person can fill it in; a client that treats that as a failure will loop. A project or organisation key is refused at any depth: the project comes from the credential, never from the body.

requestState?string

The requestState handle returned by a previous turn of the same interaction — how you answer a questionnaire. Single use: replaying it is refused with invalid_handle, and a fresh invocation without it starts over.

Response Body

`application/json`

curl -X POST "https://app.digitalyser.io/api/v1/capabilities/audit.overview.get/invoke" \  -H "Authorization: Bearer <token>" \  -H "Content-Type: application/json" \  -d '{}'

{  "capabilityId": "audit.overview.get",  "projectId": "8f14e45f-ea0e-4b1e-9b7a-2c3d4e5f6071",  "resultType": "value",  "data": {    "schemaVersion": "2"  }}

Generated from the capability registry — API version 1, 18 paths, from 4815355 (2026-10-12).

Was this page helpful?

Run a capability — returns a value, a questionnaire, or a proposal

Authorization

Path Parameters

Request Body

Response Body

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

429application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`