Versions and the envelope

Every request and every answer carries a small block under extensions.at: the envelope. It names the version you wrote against and the version that served you, identifies the call, and tells you what the call cost. This guide reads it end to end.

One serviced version

The API serves one contract version today: genesis 0 — name is the era's label, number orders compatibility. A change — any mutation — must name the version it was written against, so the platform can keep serving you the behaviour you tested against as the contract grows:

{
  "extensions": {
    "at": {
      "version": {
        "name": "genesis",
        "number": 0
      }
    }
  }
}

A change without it is refused before anything happens with VALIDATION/VERSION_REQUIRED. A read may leave the version out; the current version serves it, and the answer says so. Every operation page's example request carries the envelope line where it is needed.

What comes back

extensions.at on every answer — a success, a refusal and a rehearsal alike — carries:

• callId — this call's own id. Quote it when something needs a look; it is how a call is found again.
• version — requested, the version you named (null on a read that left it out), and serviced, the version that answered.
• stat — the service that answered, the compute time, the bytes in and out, and the change the call made to your stored records and files; a change that made a record smaller is negative.
• attribution — the organization and cost centre the call was charged to; null on a call that belongs to no one organization.
• dryRun: true — present only on a rehearsal, so a rehearsed record is never mistaken for a saved one (Dry runs).

What you may send

Beside version, the request half of the envelope takes client — the name and version of your own software, recommended so a problem can be traced to a build — reason, your reason for a change, kept with the record's history, and dryRun (Dry runs).

A refusal still carries it

An error answer keeps the envelope: the callId to quote, the version, the stat. The refusals themselves are on the errors list — Errors and retries reads them.