Skip to content
SupaCloud Docs
Select themeSelect language

`POST /api/commands/{word}/invoke` — resolve `word` with the supplied args and, when `ready`, return the structured `ResponsePlan` (text / html / media / affordances) acknowledging the resolved invocation; an under-specified or invalid invocation returns the resolver's `need_param` / `invalid` guidance instead (never a half-run). An unknown OR role-hidden word is a 404.

POST
/api/commands/{word}/invoke
curl --request POST \
  --url https://example.com/api/commands/example/invoke \
  --header 'Content-Type: application/json' \
  --cookie supacloud_session=<supacloud_session> \
  --data '{ "args": { "additionalProperty": "example" } }'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
word
required
string

Command word or alias

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

The body of POST /api/commands/{word}/resolve and .../invoke: the partial arg bindings supplied so far (param name -> value). Absent = a bare invocation; the resolver/invoker fills in / asks for the rest.

object
args

Partial argument bindings keyed by param name.

object
key
additional properties
string
Examplegenerated
{
  "args": {
    "additionalProperty": "example"
  }
}

Responses

Section titled “Responses”

200

Section titled “200”
Media typeapplication/json
One of:

Fully resolved + acknowledged; plan is the rendered reply.

object
invocation
required

A replayable command invocation (ADR §2.2): word + resolved arg bindings.

object
args
required

Resolved arg bindings (param name -> chosen value).

object
key
additional properties
string
word
required
string
plan
required

A rendered command reply (ADR §2.2). #626 chat-format inversion — text is now NEUTRAL MARKDOWN (**bold**, `code`, …); the old html flag is gone. Each client renders the one markdown source to its own format (the web terminal -> ANSI).

object
affordances
required
Array<object>

A surface-neutral “next action” attached to a reply (ADR §2.2 Affordance).

object
action
required

A replayable command invocation (ADR §2.2): word + resolved arg bindings.

object
args
required

Resolved arg bindings (param name -> chosen value).

object
key
additional properties
string
word
required
string
glyph
string | null
label
required
string
media
required
Array<object>

A media artifact (ADR §2.2 Media) on the wire — source carries url XOR data.

object
alt
string | null
data
string | null
kind
required
string
mime
required
string
name
string | null
url
string | null
text
required

The reply body in neutral markdown.

string
status
required
string
Allowed values: executed
Example
{
  "status": "executed"
}

401

Section titled “401”

Authentication required

403

Section titled “403”

Permission denied

404

Section titled “404”

No such command

500

Section titled “500”

Structured server error