Operating

API reference

Every endpoint, who may call it, and what comes back.

Two credentials appear below. Agent means the ordinary credential your agent holds. Operator means a detached signature over the GL-Operator header, held by a person, covering the operation, method, URL, timestamp, nonce and body digest.

Money

POST /pay: Agent. A signed intent: idempotencyKey, payee, amount, purpose, terms, envelope. Returns a Receipt on 200. A 202 means it is accepted and not settled, and carries the approval challenge.
POST /resolve: Agent. Takes ref, returns a Counterparty.
POST /verify: Agent. Takes a Disclosure, returns a Decision.
POST /disclose: Agent. No body. Returns this deployment's own Disclosure.
POST /quote: Agent. Takes rail (acp or ucp), merchant, currency and a non-empty lines array. Returns a priced Cart. Commits nothing and moves no money.
POST /buy: Agent. The quote fields plus idempotencyKey, purpose, terms and envelope. Returns an Order carrying the settlement Receipt. There is no amount field: the price comes from the cart the seller priced.

/buy and /quote are served by the server only on a deployment that has turned the commerce tier on. It is off by default, and a deployment that has not turned it on answers 404 on both paths.

Where they are on, /buy authorises through the same gate, audit and settle path as /pay, and is under the same fail-closed rule. Its idempotency key sits in its own namespace, so one key used on /buy and on /pay cannot collide. A cart that is not ready comes back as intent.malformed carrying the status it stopped in and the continue link, rather than a bare error.

Reading

GET /audit: Agent. cursor and limit (1 to 100, default 20).
GET /audit/stream: Agent. Server-sent events, resumable with Last-Event-ID.
GET /intents/{id}: Agent. One payment.
GET /intents/{id}/events: Agent. Everything that happened to it.
GET /usage: Agent. Requires since and until. Optional repeatable tags.
GET /openapi.json: The live contract, generated from the model the surfaces are projected from.

Operator

Every one of these requires the operator signature and a rationale of at least ten characters, which is written into the record.

POST /operator/approve: intentId, challenge, mandateId, rationale, acknowledged. Returns the Receipt.
POST /operator/refund: intentId, rationale, optional amountMinor for a partial refund.
POST /operator/kill-switch: engaged and rationale. Freezes or releases settlement.
POST /operator/circuit-breaker/reset: rationale. Clears a tripped breaker.

Webhooks

All four are operator-signed, not ordinary API calls. The signing secret is returned once, at creation, and never again.

HTTP

POST   /webhooks/endpoints        # { url, events[] } -> 201, secret shown once
GET    /webhooks/endpoints        # list
GET    /webhooks/endpoints/{id}   # one
PATCH  /webhooks/endpoints/{id}   # url, events, active
DELETE /webhooks/endpoints/{id}   # 204

Memory

POST /memory/remember: Agent. mandate, validFrom, validTo, source.
POST /memory/recall: Agent. mandate, validAt, txAt. Two clocks, deliberately.
POST /memory/assemble: Agent. mandate and a budget.
POST /memory/verify: Takes an artifact, returns whether it holds.
POST /memory/forget: Operator. mandate and rootId. Returns an erasure proof.

The protocol surface

Beyond the endpoints above, the server mounts a generated method surface walked from the protocol model: namespaces including mandate, hold, delivery, obligation, evidence, clearing, terms, dispute, insurance, stake, custody, meter, session, economics, oversight, negotiate, revocation, claim and proof.

Anything classed as an override rides the operator credential rather than the agent one: revoking a mandate, disputing a delivery, resolving a dispute, revoking an identity. The generated contract at /openapi.json is the authority on the current method list.

Headers

Authorization: The agent credential. DPoP proof of possession is supported alongside it.
GL-Operator: The operator signature, on the routes above that need one.
Idempotency-Key: Sent on payments. Idempotency is keyed on the instruction's own idempotencyKey, and a replay comes back marked as one.
X-GL-Tags: Attribution for usage reporting. Malformed tags are dropped rather than failing the call.
X-Request-Id: Echoed on every response. Send your own and it is preserved.
X-RateLimit-*: Present when the agent bucket was consumed.
Retry-After: Present whenever the problem's action is retry-as-is.