Actions

These two routes give you granular, per-action control over an action's lifecycle. Most integrators don't need them — the results array on POST /agent/continue reports every executed action's outcome in one batched call, which is the recommended flow for a normal chat loop. Use the routes below if you're driving actions individually — for example, executing them out of order, or with your own retry/UI logic per action rather than as a batch.

Mark an action as executing

POST /agent/action/:actionId/execute

Auth: API key + session token (X-Appilots-Session-Token) of the session the action belongs to.

Response — 200

{
  "success": true,
  "data": {
    "actionId": "...",
    "type": "navigate",
    "payload": { ... },
    "status": "executing"
  }
}

An actionId that doesn't exist returns 404 (NOT_FOUND).

curl

curl https://api.appilots.com/api/v1/agent/action/ACTION_ID/execute \
  -X POST \
  -H "Authorization: Bearer ak_xxxxxxxxxxxx..." \
  -H "X-Appilots-Session-Token: SESSION_TOKEN"

TypeScript

const res = await fetch(`https://api.appilots.com/api/v1/agent/action/${actionId}/execute`, {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ak_xxxxxxxxxxxx...',
    'X-Appilots-Session-Token': sessionToken,
  },
});
const { data } = await res.json();

Report an action's outcome

POST /agent/action/:actionId/complete

Auth: API key + session token (X-Appilots-Session-Token) of the session the action belongs to.

Body

Field	Type	Required	Description
success	boolean	Yes	Whether the action executed successfully.
error	string	No	Failure reason, if success is false.

Response — 200

{
  "success": true,
  "data": { "actionId": "...", "status": "completed" }
}

status is "completed" or "failed" depending on the success you reported. An actionId that doesn't exist returns 404 (NOT_FOUND).

curl

curl https://api.appilots.com/api/v1/agent/action/ACTION_ID/complete \
  -X POST \
  -H "Authorization: Bearer ak_xxxxxxxxxxxx..." \
  -H "X-Appilots-Session-Token: SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"success": true}'

TypeScript

const res = await fetch(`https://api.appilots.com/api/v1/agent/action/${actionId}/complete`, {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ak_xxxxxxxxxxxx...',
    'X-Appilots-Session-Token': sessionToken,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ success: true }),
});
const { data } = await res.json();

Related pages

• Messages & streaming — the /agent/continue batch-report flow most integrators use instead
• Agent Actions — action types, payloads, and status lifecycle