API usage patterns

The generated API Reference shows the exact path, fields and response schema for every operation. This page explains the rules that apply across operations and shows how to handle failures safely. For complete task sequences, continue to the API cookbook.

Choose the correct identity

A human PAT starts with sk-actrl-pat-. It can call all public operations when RBAC permits them. A Service Account token starts with sk-actrl-sa- and can call only the operations listed in Feature availability.

curl --request GET \
  --url https://api.airctrl.dev/v1/accounts \
  --header "Authorization: Bearer $AIRCTRL_PAT"

Do not send both identity types or place a token in a query string.

Send account context

Operations that work inside one account accept x-account-id. Some create requests also carry accountId in the body. The account ID selects context; it never grants membership or permission.

curl --request GET \
  --url "https://api.airctrl.dev/v1/projects?accountId=$ACCOUNT_ID&includeArchived=false" \
  --header "Authorization: Bearer $AIRCTRL_PAT" \
  --header "x-account-id: $ACCOUNT_ID"

If an ID belongs to another account, denies the request even when the caller can access both accounts separately.

Read lists in bounded pages

List operations that expose limit and offset start at offset 0. Keep pages small enough for your process to handle.

curl --request GET \
  --url "https://api.airctrl.dev/v1/records?accountId=$ACCOUNT_ID&limit=50&offset=0&includeArchived=false" \
  --header "Authorization: Bearer $AIRCTRL_PAT" \
  --header "x-account-id: $ACCOUNT_ID"

An empty data result means no visible resources matched. It does not mean expanded the query to another scope.

Distinguish metadata from plaintext

Record endpoints return encrypted material and safe metadata. The API never returns decrypted secret fields. Use @airctrl/sdk, the CLI or MCP on a trusted machine when you need plaintext.

curl --request GET \
  --url "https://api.airctrl.dev/v1/records/$RECORD_ID" \
  --header "Authorization: Bearer $AIRCTRL_TOKEN"

The response can contain ciphertext and wrapper metadata. Do not treat either as plaintext.

Use idempotency keys for writes

Create one UUID for one intended write. Reuse that key only when retrying the same body.

IDEMPOTENCY_KEY="$(uuidgen)"

curl --request POST \
  --url https://api.airctrl.dev/v1/projects \
  --header "Authorization: Bearer $AIRCTRL_PAT" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data "{\"accountId\":\"$ACCOUNT_ID\",\"name\":\"Payments\",\"description\":\"Payment service credentials\"}"

A retry with the same key and body reuses the result. The same key with different input returns 409 and idempotency_key_reused_with_different_params.

Update only with current state

Some update operations replace their complete editable input; others patch only supplied fields. Read the operation description before sending the request.

curl --request PATCH \
  --url "https://api.airctrl.dev/v1/projects/$PROJECT_ID" \
  --header "Authorization: Bearer $AIRCTRL_PAT" \
  --header "x-account-id: $ACCOUNT_ID" \
  --header "Content-Type: application/json" \
  --data '{"name":"Payments production","description":"Production credentials","isActive":true}'

For a complete replacement contract such as this one, omitting a value is not the same as preserving it.

Treat destructive operations as two steps

First read the resource and display its name and ID. Execute the destructive request only after a human confirms that target.

curl --request DELETE \
  --url "https://api.airctrl.dev/v1/gateways/$GATEWAY_ID" \
  --header "Authorization: Bearer $AIRCTRL_PAT" \
  --header "x-account-id: $ACCOUNT_ID"

Deleting a gateway disables it and revokes its gateway tokens. It does not revoke shared provider credentials.

Read the error envelope

{
  "ok": false,
  "error": {
    "code": "forbidden",
    "message": "insufficient_permission"
  },
  "requestId": "req_example"
}

Use error.code for the HTTP category and error.message for the specific reason. Store requestId with diagnostics, but never store bearer tokens or plaintext fields.

Retry only temporary failures

Retry 429, 500 and 503 with exponential backoff, jitter and a maximum attempt count. Do not retry 400, 403 or 404 unchanged.

const retryable = new Set([429, 500, 503])
const maximumAttempts = 4

for (let attempt = 1; attempt <= maximumAttempts; attempt += 1) {
  const response = await fetch(url, request)
  if (response.ok) break
  if (!retryable.has(response.status) || attempt === maximumAttempts) {
    throw new Error(`AIRCTRL request failed with ${response.status}`)
  }
  await new Promise((resolve) => setTimeout(resolve, 250 * 2 ** (attempt - 1) + Math.random() * 100))
}

For a retried write, keep the same idempotency key and exact request body.

One-time values

Gateway token creation returns plaintext once. Provider credential creation accepts plaintext once. Send those values only between the trusted caller and the approved custody destination.

curl --request POST \
  --url "https://api.airctrl.dev/v1/gateways/$GATEWAY_ID/tokens" \
  --header "Authorization: Bearer $AIRCTRL_PAT" \
  --header "x-account-id: $ACCOUNT_ID" \
  --header "Content-Type: application/json" \
  --data '{"name":"Local development","scopes":["run","read_logs"],"expiresInDays":30}'

Later list requests return only token metadata and prefix.

Validate before automation

Before placing a request in a job:

Run it once with a test project and least-privilege identity.
Confirm the success envelope and expected audit event.
Exercise one validation failure and one permission failure.
Confirm retry behavior with a fixed idempotency key.
Remove test resources through the documented lifecycle operation.

​Choose the correct identity

​Send account context

​Read lists in bounded pages

​Distinguish metadata from plaintext

​Use idempotency keys for writes

​Update only with current state

​Treat destructive operations as two steps

​Read the error envelope

​Retry only temporary failures

​One-time values

​Validate before automation