Open a receipt before a side effect

Rules are checked first. 201: allowed, do it and confirm. 200 with duplicate: true: this idempotency key was already used, do not do it again. 202: a person must approve first, wait on waitUrl; when they answer, the receipt becomes approved (do it, then confirm) or refused. 402 quota_exceeded: it needs a person and the plan has no fixes left; the receipt is recorded as needs_person, do not do it. 403 authority_refused: a rule forbids it. 409 not_approved: approvedBy does not cover this action. Unconfirmed past deadlineAt, a person is asked to check. The same idempotencyKey after failed reopens the same receipt (201, retried: true), keeping its approval; refused is final. Limits count a running total per agent and currency over their window (a day unless the rule says otherwise); several small ones that pass it together come back with authority.pattern: "split". 429: a person must decide but this agent may not open another wall now (rate_limited, agent_paused); the receipt is recorded as needs_person, do not do it, retry after retryAfterSeconds.

post/v1/receipts

Request

  • Base URL: https://api.doubleoh.ai
  • URL: https://api.doubleoh.ai/v1/receipts
  • Auth: one of:
    • API key in header x-api-key
    • HTTP bearer

Request body

toolstring required
actionstring required

What it does, in one sentence.

argsunknown
targetstring
agentstring

Optional. The key's own agent wins; another name on a key bound to an agent is 400 agent_mismatch.

idempotencyKeystring

One per real-world action, the same on every retry. Defaults to tool + args hash + the minute.

amountCentsinteger
currencystring
confirmWithinSecondsinteger
approvedBystring

An intervention id a person answered with approved: true in the last hour, on this key, asked by the same agent, for the same tool and action (and site, when it had one), and for at least this amount in the same currency (a receipt with an amount needs a yes that had one, and a yes with an amount needs the receipt to send it). One approval backs exactly one receipt; a second use is 409 not_approved. The receipt opens as approved, with no new wall and no second page.

Response

Duplicate: already done or in progress.

duplicateboolean
interventionIdstring nullable

Always present: the wall this receipt waits on or was approved through, else null.

waitUrlstring

When it is still waiting on a person.

confirmUrlstring
nextstring

Changes

No recorded changes to this operation across all 1 revision of this API.