Intents API

An intent is a signed, structured request to execute a named action on one or more agents. The control plane signs the intent with its VaultysId before routing it — agents verify this signature before executing.

Send an intent

POST /api/intents

Auth: Required. Non-admin users must have a capability grant for the action.

Returns 202 Accepted immediately. The intent is routed to the target agent(s) asynchronously.

Request body

{
  "agentId": "did:vaultys:z6Mkf9x3TQ...",
  "action": "summarise_document",
  "params": {
    "url": "https://internal.acme.com/reports/q1-2026.pdf",
    "format": "bullet_points",
    "maxWords": 300
  }
}

Field	Type	Required	Description
agentId	string	No	Target agent DID. Omit to broadcast.
action	string	Yes	The action name to execute
params	object	Yes	Action-specific parameters
broadcastCapability	string	No	When broadcasting (no agentId), only send to agents that have this capability

Broadcast to all capable agents

Omit agentId to broadcast to all connected agents:

{
  "action": "health_check",
  "params": {}
}

Or broadcast only to agents with a specific capability:

{
  "broadcastCapability": "internet_access",
  "action": "fetch_news",
  "params": { "topic": "AI regulation" }
}

Response 202 Accepted

{
  "intentId": "int_01HZABC...",
  "action": "summarise_document",
  "sentTo": ["did:vaultys:z6Mkf9x3TQ..."],
  "count": 1
}

Field	Description
intentId	Unique ID for this intent (used for replay prevention)
sentTo	Array of agent DIDs that received the intent
count	Number of agents the intent was sent to

Error: no capable agents online

{
  "error": "No agents available",
  "message": "No connected agents match the requested capability"
}

Error: insufficient permissions

{
  "error": "Forbidden",
  "message": "You do not have a capability grant for 'code_execution' on this agent"
}

List intents

GET /api/intents

Auth: Required.

Coming soon

Full intent history with results is currently in development. This endpoint returns a placeholder response.

{
  "intents": [],
  "message": "Intent history coming soon"
}

Action naming conventions

Actions are arbitrary strings — VaultysClaw does not enforce a naming scheme. By convention, use snake_case verbs:

Example action	Description
echo	Built-in test action; returns params as output
chat_completion	Ask the agent's LLM a question
summarise_document	Summarise a document at a URL
send_email	Send an email (requires mail_send capability)
run_code	Execute a code snippet (requires code_execution)
fetch_url	Fetch and return HTTP response (requires internet_access)
search_web	Web search (requires internet_access)
read_file	Read a local file (requires file_access)
write_file	Write a local file (requires file_access)

Custom agents can define any action name. The CAPABILITY_MAP in the agent controller maps action names to the required capability.