All docs

API reference: Operations

Check on work Formspring accepted for later: imports, exports, document generation, bulk actions, rollouts and refunds whose outcome is still unknown.

Updated . 3 min read.

Some requests are accepted now and finished in the background: an import, an export, a bulk action, a generated document, a rollout to client workspaces, a delete. These answer 202 Accepted. Every such answer carries an operation object and a Location header that point to one place to check on the work, whatever kind of work it is.

Base URL: https://formspring.io/api/v1

Method Path Ability
GET /operations/{id} Any valid token

An operation is visible to the person who started it and to the workspace owner and administrators, and only while they may open the project it belongs to. Anyone else gets 404, so an id reveals nothing.

The accepted answer

http
DELETE /forms/AbC12xyz/force

Response 202 (the fields the endpoint always returned are unchanged; operation is added):

json
{
  "ok": true,
  "queued": true,
  "operation": {
    "id": "op_01j9z6c4k0m3x8w2q7r5t1v9yb",
    "kind": "forms.force-delete",
    "state": "queued",
    "status_url": "https://formspring.io/api/v1/operations/op_01j9z6c4k0m3x8w2q7r5t1v9yb"
  }
}

The Location header holds the same status_url. An answer that did not queue any background work has no operation.

Check an operation

http
GET /operations/op_01j9z6c4k0m3x8w2q7r5t1v9yb

Response 200:

json
{
  "data": {
    "id": "op_01j9z6c4k0m3x8w2q7r5t1v9yb",
    "kind": "forms.force-delete",
    "state": "succeeded",
    "terminal": true,
    "subject": { "type": "form", "id": "AbC12xyz" },
    "project_id": 12,
    "result": { "refs": [] },
    "error": null,
    "progress": { "jobs_total": 1, "jobs_pending": 0 },
    "created_at": "2026-10-30T09:14:02+00:00",
    "started_at": "2026-10-30T09:14:03+00:00",
    "finished_at": "2026-10-30T09:14:04+00:00",
    "status_url": "https://formspring.io/api/v1/operations/op_01j9z6c4k0m3x8w2q7r5t1v9yb"
  }
}
State Meaning
queued Accepted, nothing has started
running At least one background step has started
succeeded Every step finished
failed A step gave up; error.code and error.message say why
needs_review The outcome is unknown or needs a person, for example a payment provider that did not answer a refund. Do not repeat the request: Formspring checks with the provider and moves the operation to succeeded or failed
cancelled Stopped before it finished

Poll until terminal is true. Finished operations are kept for 30 days. An operation whose background steps never reported back for 12 hours moves to needs_review with the error code stalled.

Retrying safely

Send an Idempotency-Key header on requests that move money, send messages, cancel bookings or roll out changes. The same key with the same body returns the first answer, including its operation, and runs nothing twice. The same key with a different body answers 409 (idempotency_key_reused). Keys are remembered for seven days.

Agents and the mobile app

AI agents read the same resource with the get_operation tool. The mobile app receives the same operation object on its accepted answers, with a status_url under /api/v1/mobile/operations/{id}.