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: required.

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..."

TypeScript

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

Report an action's outcome

POST /agent/action/:actionId/complete

Auth: required.

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 "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...",
      "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