Response action API

Response action API

Request bounded response actions, approve exact revisions, cancel pending work, and inspect acknowledgement.

Actions require Responder authority and target capabilities. Approval requires a separately authorized approver. Read response execution and quarantine recovery before automation.

Use the shared API contract for authentication, pagination, request headers, idempotency, and error responses.

Request an action

POST/organizations/{organization_id}/actions
Scope
actions:request
Auth
Bearer API key

Creates a response request for one action type. Targets and parameters are immutable after acceptance. Unsupported controls return 422 unsupported_capability before admission.

Request body
incident_idstringrequired

Visible incident authorizing the investigation context.

typestringrequired

Requested executor effect.

one ofisolate, release_isolation, quarantine, restore_quarantine
endpoint_idsstring[]required

Authorized endpoint targets. Quarantine and restoration require exactly one endpoint.

rule1–200 unique IDs
artifactobjectoptional

Required only for quarantine: observed absolute path and expected 64-character SHA-256 hex digest. Forbidden for all other action types.

quarantine_idstringoptional

Required for restoration and forbidden for other types; identifies the protected item.

destinationstringoptional

Absolute restoration path. Allowed only for restoration; omission uses the recorded original path. An existing different file cannot be overwritten.

expires_attimestampoptional

Future execution-start deadline. Omission uses creation plus 900 seconds.

default15 minutes after creationrule60–86400 seconds after creation
reasonstringrequired

Audited justification. Empty values are invalid.

rule1–2000 characters
202Accepted

The response is similar to the following:

JSON
{
  "data": {
    "id": "act_001",
    "type": "isolate",
    "state": "pending_approval",
    "endpoint_ids": ["end_laptop01"],
    "expires_at": "2026-03-04T10:15:00Z"
  },
  "operation": {
    "id": "op_001",
    "state": "queued"
  },
  "request_id": "req_action01"
}

Read an action

GET/organizations/{organization_id}/actions/{action_id}
Scope
actions:read
Auth
Bearer API key

Returns state, exact targets and parameters, approval revision, deadline, operation, and each target's acknowledgement or error. Succeeded requires acknowledged execution; no heartbeat is not success.

200Result

Returns data and request_id.

Decide an approval

POST/organizations/{organization_id}/actions/{action_id}/approval
Scope
actions:approve
Auth
Bearer API key

Records an approval decision for the exact action revision. Requires If-Match. Self-approval is rejected when separation is required. Changed or expired requests return 409.

Request body
decisionstringrequired

Approve or reject the reviewed request.

one ofapprove, reject
reasonstringrequired

Audited justification. Empty values are invalid.

rule1–2000 characters
200Result

Returns the approval record and action state. Approved actions queue for execution; approval is not execution acknowledgement.

Cancel an action

POST/organizations/{organization_id}/actions/{action_id}/cancel
Scope
actions:request
Auth
Bearer API key

Cancels pending admission or cancelable work. Completed isolation or quarantine remains applied. A non-cancelable phase returns 409 cancellation_unavailable.

Request body
reasonstringrequired

Audited justification. Empty values are invalid.

rule1–2000 characters
202Accepted

Returns action data and cancellation operation. An already completed effect requires a new authorized inverse action.

List actions

GET/organizations/{organization_id}/actions
Scope
actions:read
Auth
Bearer API key

Returns action summaries. Use the single-action read for target-level outcome and partial failure details. Standard limit and cursor apply. Unknown filters return 422.

Query parameters
incident_idstringoptional

Filter visible investigation.

endpoint_idstringoptional

Filter execution target.

statestringoptional

Action state.

one ofpending_approval, queued, running, succeeded, failed, rejected, canceled, expired
200Result

Returns a data array and pagination.next_cursor. Entries include stable IDs and the resource fields described for this collection.