Ablo API

Ablo collaboration infrastructure: commit, read, and claim. {model} is any model from your pushed schema — the routes are the same whichever it is. Authenticate every request with your API key as a Bearer token.

Versioning

Every route is mounted under /v1, and that segment is part of the address you call. A change that would break a caller — a field removed, a type narrowed, a status changed — arrives as a new segment beside this one, never as a change to this one. Additive changes do land here: a new field on a response, a new optional parameter, a new error code. Ignore what you do not recognize and you will not be broken by them.

Every response carries Ablo-Version, a date stamp for the contract the server is serving. Record the value your integration was built against and compare it if behavior surprises you.

Deprecation

A route being withdrawn says so on itself, for at least 180 days before it stops answering:

• Deprecation — an sf-Date of when the deprecation took effect (RFC 9745). The route still answers normally while this is present.
• Sunset — an HTTP-date of when it stops answering (RFC 8594).
• Link with rel="deprecation" pointing at what to read, and rel="successor-version" at what to call instead when there is one.

The same operations are marked deprecated: true in this document. Treating either signal as a build failure is the intended use; nothing is removed without both.

models

• GETList rows of a model/v1/models/{model}
• POSTCreate a row/v1/models/{model}
• GETRetrieve a row/v1/models/{model}/{id}
• DELETEDelete a row/v1/models/{model}/{id}
• PATCHUpdate a row/v1/models/{model}/{id}

claims

• POSTClaim a row (acquire lease)/v1/models/{model}/{id}/claim
• DELETERelease a claim/v1/models/{model}/{id}/claim
• POSTHeartbeat a held claim (extend the lease for long-running work)/v1/models/{model}/{id}/claim/heartbeat
• POSTReorder the wait-line (privileged)/v1/models/{model}/{id}/claim/reorder
• GETList who holds what, and who waits/v1/claims
• POSTClaim a row named in the body/v1/claims
• POSTHeartbeat every lease you hold, in one request/v1/claims/heartbeat
• GETPoll a claim for its current state/v1/claims/{claimId}
• DELETERelease a claim, or leave the wait line/v1/claims/{claimId}
• POSTHeartbeat a claim by id — held or queued/v1/claims/{claimId}/heartbeat

credentials

• POSTMint a short-lived session credential/v1/ephemeral_keys
• POSTMint a capability for an agent or system/v1/capabilities
• GETInspect a capability/v1/capabilities/{id}
• DELETERevoke a capability/v1/capabilities/{id}
• POSTRotate a capability, keeping its grant/v1/capabilities/{id}/rotate

branches

• GETList transaction branches for the credential project/v1/branches
• POSTCreate an isolated child branch/v1/branches
• GETRetrieve a branch by immutable id/v1/branches/{id}
• DELETEDelete a non-root branch and revoke its credentials/v1/branches/{id}
• POSTMint an expiring branch-bound test credential/v1/branches/{id}/credentials
• GETDiagnose one branch/v1/branches/{id}/status

schema

• GETWhat the models look like/v1/schema

logs

• GETTail what changed/v1/logs
• GETHow much of what was recorded could reach anyone/v1/logs/delivery

commits

• GETList commit records/v1/commits
• POSTCommit a batch of operations atomically, and/or register durable premises/v1/commits
• GETRetrieve a commit record/v1/commits/{id}