Automation API
Use organization-scoped authentication, consistent envelopes, revisions, pagination, and safe retries.
The Guard management API reads security resources and requests configuration or response work. API admission never substitutes for executor acknowledgement.
Base URL and organization scope
Use the HTTPS origin supplied in Organization → API access, followed by /api/v1/guard. Self-hosted installations use their configured public origin. All endpoint-card paths in this reference are relative to that prefix and include /organizations/{organization_id}. Replace path parameters with stable IDs; never substitute display names.
Send Accept: application/json and Authorization: Bearer API_KEY. JSON requests also require Content-Type: application/json. Path parameters are nonempty strings identifying the organization and named resource; an out-of-scope or missing resource returns 404. Replace API_KEY with the service-account key. The authenticated organization must match the path.
Authentication
Create a key at Organization → Service accounts → Account → Create key. Its permitted operations are the intersection of its role, allowed asset groups, and scopes. Read scopes do not authorize writes, and an action-request scope does not authorize approval. Evidence access and employee-sensitive detail require their independent grants. See identity and access.
| Scope family | Operations |
|---|---|
assets:read, assets:write | Inventory and group selection |
endpoints:read, endpoints:write | Enrollment, endpoint metadata, retirement |
policies:read, policies:write | Drafts, publication, assignments |
network:read, network:write | Protected service routing configuration |
intelligence:read, intelligence:write | Indicators and reviewed contributions |
assessments:read, assessments:write | Scan scopes, runs, finding review |
access:read, access:write | Applications, access policies, session revocation |
incidents:read, incidents:write | Detection review and incident work |
actions:read, actions:request, actions:approve | Response observation, requests, approval |
evidence:read, evidence:write, evidence:hold | Artifact metadata, exports, collection, holds |
reports:read, reports:write | Report generation and downloads |
integrations:read, integrations:write | Destination configuration and delivery replay |
operations:read, operations:cancel | Polling and cancellation |
Envelopes and fields
Single reads and synchronous changes return data. Collections return data plus pagination.next_cursor; null means this traversal has ended. Accepted asynchronous work returns 202 with data, operation, and request_id. Read the operation before dependent work.
An accepted response is similar to the following:
{
"data": { "id": "act_001", "state": "queued" },
"operation": { "id": "op_001", "state": "queued" },
"request_id": "req_001"
}Timestamps are RFC 3339 UTC strings. Durations use integer seconds; sizes use integer bytes. Unknown writable fields, invalid types, invalid enums, and unsupported nulls return 422 without applying the requested update. PATCH preserves omitted fields. Names are 1–120 non-whitespace characters unless an entry gives a narrower bound; free-text reasons are 1–2000 characters. IDs are opaque strings. Ignore unrecognized response fields so additive API changes do not break the client.
Pagination and filtering
Every collection accepts integer limit from 1 through 200, default 50, and optional opaque cursor. Pass the returned cursor unchanged. Each operation lists additional filters; unknown filters and malformed values return 422. Results are permission filtered. Concurrent updates can change later pages; deduplicate by ID and use a bounded report for a fixed collection cutoff.
Idempotency and concurrency
Creation and action requests accept Idempotency-Key, a nonempty value up to 128 characters. Keys are organization scoped and retained for 24 hours from initial acceptance. Identical requests return their recorded result after authorization is rechecked. A changed method, path, or JSON body with the same key returns 409 idempotency_conflict. After expiry, reconcile current state before sending new work.
Configuration reads return ETag. PATCH, publication, retirement, and deletion require the latest value in If-Match; absent conditions return 428, stale conditions return 412 revision_conflict. Action approvals bind the exact action revision and require its ETag. An ETag is a configuration revision, not proof a device applied it.
Errors and retry
Error responses identify the cause and the request ID:
{
"error": {
"code": "unsupported_capability",
"message": "The endpoint cannot perform the requested action.",
"details": { "endpoint_id": "end_laptop01", "action": "isolate" }
},
"request_id": "req_002"
}| Status | Meaning | Next action |
|---|---|---|
400 | Malformed JSON | Correct framing |
401 | Invalid, expired, or revoked credential | Replace the credential |
403 | Missing role, scope, or special grant | Review authorization |
404 | Missing or invisible resource | Check IDs and organization |
409 | State, dependency, approval, or retry-identity conflict | Inspect the named conflict |
412 | Stale ETag | Read and reconcile the current revision |
422 | Invalid fields or unsupported combination | Correct the reported fields |
428 | Required condition missing | Send current If-Match |
429 | Rate limit | Wait for Retry-After seconds |
503 | Required service unavailable | Check state, then retry with backoff |
Responses expose RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset. Use bounded exponential backoff with jitter for retryable transport and server errors; reuse the same idempotency key for the same intended write. Do not retry authorization or validation failures unchanged. A client timeout does not cancel work.
Resource references
Start with Assets, Endpoints, and Policies for inventory and desired configuration. Use Network, Assessments, Intelligence, and Access for domain configuration. Investigation uses Incidents, Actions, Evidence, Reports, and Integrations.