Operations

Some actions kick off work that may take a moment — buying a domain, for example. Those endpoints return an operation_id; you poll the operation here until its status reaches a terminal state (succeeded or failed) instead of re-firing the action and re-triggering the side effect.

An operation is a durable, read-only handle. You never mutate one — you read it until it settles. A synchronous action that completes inline still writes an operation row (inserted already-terminal), so the polling contract is uniform whether the work was async or not.

Endpoints

Lifecycle

pending → running → succeeded
                 ↘ failed

pending (accepted, not started) and running are non-terminal — keep polling. succeeded and failed are terminal — stop. On failed, failed_reason carries a short, customer-safe explanation. On succeeded, result holds the outcome payload (shape depends on kind).

GET /admin/projects/:projectId/operations

Query

Response 200

{
  "data": [
    {
      "id": "…",
      "kind": "domain_purchase",
      "status": "succeeded",
      "failed_reason": null,
      "result": { "domain": "example.com" },
      "metadata": { "domain": "example.com" },
      "created_at": "…",
      "updated_at": "…"
    }
  ]
}

Errors

• 400 INVALID_QUERY — bad kind (too long) or status (not a lifecycle value).
• 500 LIST_FAILED.

GET /admin/projects/:projectId/operations/:operationId

Reading a still-running handle for an async action self-reconciles: the server re-checks the underlying work and settles the handle to its terminal status before returning. So polling this endpoint alone drives the action to completion — you don't need to also poll the producing resource.

Response 200

{
  "data": {
    "id": "…",
    "kind": "domain_purchase",
    "status": "running",
    "failed_reason": null,
    "result": null,
    "metadata": { "domain": "example.com" },
    "created_at": "…",
    "updated_at": "…"
  }
}

Errors

• 400 INVALID_OPERATION_ID — not a valid UUID.
• 404 NOT_FOUND — no such operation on this project.
• 500 GET_FAILED.

Try it:

curl -X GET 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/operations'

Curl:

# Poll until status is succeeded | failed
curl -X GET '${BASE_URL}/admin/projects/{projectId}/operations/{operationId}' \
  -H 'Authorization: Bearer ${DEVELOPER_TOKEN}'

MCP tools

Producing tools (e.g. amba_domains_purchase) return the operation_id; pass it to amba_operations_get and re-call until it settles rather than re-running the action.

Reference

• Domains — the first producer of operation handles (kind: domain_purchase).