Reference

Operations API Reference

The Operations API is the interface exposed by the in-account TierPilot Operator. It is the only channel through which storage-class changes happen. TierPilot's control plane is its primary caller, but the API is documented so you can audit it, call it from your own tooling, or build approval workflows around it.

Endpoint and authentication

The operator is a Lambda function URL (or API Gateway endpoint on Enterprise) in your account:

POST https://<operator-id>.lambda-url.<region>.on.aws/v1/<action>

Every request body is a signed envelope:

{
  "payload":   { ... },            // action-specific
  "nonce":     "b1f4...",          // single-use
  "expires_at": "2026-07-18T12:00:00Z",
  "signature": "ed25519:..."       // over payload + nonce + expiry
}

The operator verifies the Ed25519 signature against the public key installed with the stack, rejects expired or replayed nonces, and enforces your guardrails on every action regardless of what the payload requests.

POST /v1/plans — submit a transition plan

{
  "plan_id": "plan_2026_07_17_001",
  "transitions": [
    { "object_ref": "obj_9f3ba2e1c8", "target": "GLACIER_IR" },
    { "object_ref": "obj_44c1d0a7b2", "target": "DEEP_ARCHIVE" }
  ],
  "max_rps": 50
}

The operator resolves each object_ref to a key locally (using the in-account salt), drops any transition violating excluded prefixes or tier floors, and executes the rest as copy-in-place transitions at up to max_rps requests/second.

Response:

{ "plan_id": "plan_2026_07_17_001", "accepted": 2, "rejected": 0, "status": "executing" }

GET /v1/plans/:plan_id — plan status

{
  "plan_id": "plan_2026_07_17_001",
  "status": "completed",           // queued | executing | completed | partial | failed
  "executed": 7183411,
  "failed": 12,
  "skipped_guardrail": 3025,
  "started_at": "2026-07-17T02:10:11Z",
  "completed_at": "2026-07-17T09:44:02Z"
}

POST /v1/plans/:plan_id/cancel — halt execution

Stops issuing new transitions immediately. In-flight S3 calls complete; nothing is rolled back (transitions are individually safe and reversible by a later plan).

GET /v1/health — operator status

{ "version": "1.8.2", "salt_ok": true, "guardrails_loaded": true, "last_plan_at": "2026-07-17T02:10:11Z" }

Errors

Code	Meaning
`401 invalid_signature`	Signature verification failed.
`409 replayed_nonce`	Nonce already used; plan rejected.
`410 expired_envelope`	Envelope past `expires_at`.
`422 unknown_object_ref`	Token not resolvable in this account.
`429 rate_limited`	Operator throttling to protect your S3 API limits.

Questions or a use case the API doesn't cover? Book a demo — the roadmap is driven by these conversations.