Skip to main content
POST
Error

Authorizations

​
Authorization
string
header
required

The control surface credential. Send Authorization: Bearer <token>.

Two kinds of token are accepted and they are told apart by shape, not by a separate header. A token beginning pbk_ is an org scoped API key, whose public half and secret half are generated together and of which only a hash of the secret is ever stored; anything else is treated as an OAuth 2.1 access token and verified against the authorization server's keys.

Both resolve to the same context: an org, a principal and a set of scopes. Nothing downstream branches on which channel you used, with one deliberate exception, key management, which requires a signed-in person so that a key can never mint another key.

Scopes are enforced when MCP tools are REGISTERED rather than when they are called, so a tool your credential cannot use is absent from tools/list rather than refused mid gesture.

Headers

​
Idempotency-Key
string
required

Required for an inventory refresh. The same organization, actor, key and canonical request return the original result. A changed intent conflicts. Query the original /requests/{requestKey} after a lost response; no automatic mutation retry. Caller-generated unique intent key, retained by client before sending. New library restriction, not a change to the legacy visible-ASCII key contract.

Required string length: 1 - 128
Pattern: ^(?!\.{1,2}$)[A-Za-z0-9._:-]+$
Example:

"save.20260930.001"

Body

application/json

Explicit finite scope. Omit packageName to collect the full installed-app inventory. Pure read only: never acquire/renew leases, wake/boot devices or run a substitute app action. Unsupported read-only transport returns a per-target reason.

​
targets
object[]
required
Required array length: 1 - 100 elements
​
packageName
string
Required string length: 1 - 255
Pattern: ^[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z][A-Za-z0-9_]*)+$
Example:

"com.example.notes"

Response

Accepted; follow returned resource.

​
refreshId
string
required
Pattern: ^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$
Example:

"app_01"

​
state
enum<string>
required
Available options:
processing,
completed,
partially_completed,
not_completed
​
requestedAt
string<date-time>
required
Example:

"2026-09-30T18:00:00Z"

​
finishedAt
string<date-time> | null
required
Example:

"2026-09-30T18:00:00Z"

​
targetCount
integer
required
Required range: x >= 1
​
completedCount
integer
required
Required range: x >= 0
​
notCompletedCount
integer
required
Required range: x >= 0
​
nextPollAfterSeconds
integer
required
Required range: x >= 1
​
servicePromise
object
required

Original promisedBy never resets on retry/poll. nextUpdateAt must correspond to a real scheduled update and accountable service; null does not authorize indefinite waiting.

Example: