Contents
Start here
TERSL — the language
TERSL/DB — the system
Portal guide
HTTP API
Reference
HTTP API

Headers

Every request header a client can send to TERSL/DB and every response header it can receive, with the routes, the value rules and the answer to a malformed value.

Overview#

This page lists the HTTP headers TERSL/DB reads and writes. The first table is the request headers: which routes read each one, what value it takes, and what a malformed value answers. The second table is the response headers: when each one is present and what it carries.

When a request header appears more than once, the last value is used, so a proxy that appends a value cannot change the answer. Header names are matched case-insensitively, as HTTP requires; values are case-sensitive unless a row says otherwise.

Request headers#

Header Routes Value and rule Malformed value answers
Authorization every namespace route, /v1/ns Bearer <secret>. The scheme is case-insensitive. Any other scheme, such as Basic, is a refusal; the service does not then read Terse-Key. the empty 404
Terse-Key every namespace route, /v1/ns The secret on its own. Ignored when Authorization is present. the empty 404
Terse-Seam /issue The seam token: non-empty, printable ASCII U+0021 to U+007E only, so no spaces, tabs or line breaks. The response is framed with the same token. 400 naming the header
Expected-Csn /issue; /load (first applied batch only) A non-negative integer: the head CSN the write expects. A mismatch is a 200 with the refusal in the Messages channel, and nothing is applied. 400
Terse-As-Of-Csn /issue, /export A non-negative integer. Reads as of that CSN; a CSN past the head is the head. Queries only. 400
Terse-As-Of /issue, /export An RFC 3339 time with an offset. Reads as of the newest entry committed at or before it. Queries only. 400; both as-of headers together is a 400; either one beside an @ address is a 400
Terse-Agent namespace routes The client's name for itself, recorded with each entry it writes. Trimmed; printable ASCII 0x20 to 0x7E; at most 128 characters. 400 naming the header
Terse-Correlation-Id namespace routes An id that ties the request to the caller's own records. Same rule as Terse-Agent. 400
traceparent namespace routes W3C Trace Context. Used as the correlation id when Terse-Correlation-Id is absent, and held to the same rule. 400
Terse-Idempotency-Key /issue, /load 1 to 128 printable ASCII characters after trimming. A resend with the same key and the same body is answered from the record instead of being applied again; the same key with a different body is a 422 with TERSE-IDM-001. On /load, batch k is sent under <key>:<k>. 400; present but blank is a 400
Terse-Load-Exclusive /load none, writes or all; default none. writes refuses other Issues that carry declarations while the load runs; all refuses every other Issue and history read on the namespace. Refused requests get 503 with TERSE-LOAD-002. 400
Terse-Load-Batch-Bytes /load A positive integer: the size at which the file is cut into batches. Clamped to between 1 MiB and the deployment's batch ceiling, and to 64 KiB below the plan's request-size limit. 400
Terse-Load-Dry-Run /load true or false; default false. true plans the file, reports the plan and applies nothing. 400
Terse-Load-On-Error /load stop (default) or continue. Under continue, a batch refused for a content limit (413) or a batch whose declarations the service would not apply (409) is skipped and the load goes on; every other refusal, and an Expected-Csn mismatch, stops the load. 400
Terse-Load-Skip-Lines /load An integer N of 0 or more. The whole file is still read and planned; nothing at or before file line N is applied. 400
Content-Length /issue, /load Compared, before any of the body is read, with the plan's request-size limit (/issue) or the deployment's load limit (/load). 413
Content-Type /issue, /load Send text/plain; charset=utf-8. The body is decoded as strict UTF-8; an invalid sequence is a 400. —

The as-of headers and the @ address form are three spellings of one request; see Addresses. Expected-Csn and Terse-Idempotency-Key are the two ways to make a resend safe; see Status codes.

Response headers#

Header When it is present Value
Terse-Csn Every 200 of /issue, /history, /export, /explain and /seal; the fork 202; the write-contention 503. The head CSN after the declarations were applied. On a point-in-time read, the CSN served. On the contention 503, the head that stands. On /seal, the seal's CSN.
Terse-Chain Every 200 of /issue, /history and /export on a namespace with a verifiable record. Absent, not empty, on other namespaces. The chain value of the newest entry. On a point-in-time read, the chain value of the entry served.
Terse-Seal-Csn A 200 that carries Terse-Chain, when the namespace's record is sealed and a seal exists at or below the CSN answered. The newest sealed CSN at or below the CSN answered.
Terse-As-Of-Csn A point-in-time 200 of /issue or /export; every playback answer. The CSN the request's time or CSN resolved to. On playback, the session's position.
Terse-Diagnostics Every /issue answer that reached processing: the 200, and the 413 with a TERSE-LIM code, 422, 500, 507, and the 503 for a held writer, write contention or the memory limit. Also on /export refusals. Never on a refusal given earlier. errors=N; warnings=M, counting the error: and warn: lines in the body. errors=0; warnings=0 when there is nothing to say.
Server-Timing The same answers as Terse-Diagnostics, and any answer that waited for a rate limit. Entries parse, apply (or head when there were no declarations), fold on a point-in-time read, query and total, each as name;dur=<ms>. When the request waited for its rate limit, governor;dur=<ms> comes first.
RateLimit-Policy, RateLimit Every answer to an admitted caller on an account with plan rates, 2xx and 429 alike. The format of draft-ietf-httpapi-ratelimit-headers-11. RateLimit-Policy lists the account's windows: "ceiling", "requests", "requests-30d", "writes", "writes-30d", each with q= and w=. RateLimit names the one window with the least headroom, or the window that refused, as "name";r=<remaining>;t=<seconds to full>.
Retry-After Every 429 and 503. Never on 400, 413, 422, 500 or 507. Seconds to wait. For a rate-limit refusal, the exact wait. For an exclusive load, an estimate from the bytes remaining, between 5 seconds and 1 hour. For other refusals, a fixed interval the service sets.
Terse-History-Next A history 200 that did not consume its range. The last CSN read plus one: the from for the next page.
Terse-History-Verified Every history 200. ok, unchained, violation, or violation csn=N. The CSN is given only to a key whose history covers the whole namespace.
Terse-Load-Id Every /load response once its 200 has started. Absent on refusals given before the body is read. 12 hexadecimal characters identifying the load. It is also the second word of the stream's load line.
Terse-Playback Every playback answer. The session id, 32 lower-case hexadecimal characters.
Location The fork 202, the scrub 202, the playback 201. /v1/ns/{ns}/fork/{fork}, /v1/ns/{ns}/scrub or /v1/ns/{ns}/playback/{id}. Always the bare namespace name, even when the request used an address.
Content-Disposition The export 200. attachment; filename="<ns>-<csn>.terse"; filename*=UTF-8''…
Cache-Control /.well-known/terse-seal-keys. public, max-age=3600
Content-Type Every answer with a body. text/plain; charset=utf-8, except application/jwk-set+json on /.well-known/terse-seal-keys.

What a refusal carries#

A refusal given before the service processed the request carries no measurement: no Terse-Csn, no Terse-Diagnostics and no phase entries in Server-Timing. Two headers are the exception, and only for a caller who authenticated and was admitted: RateLimit-Policy and RateLimit on every answer to an account with plan rates, and Server-Timing: governor;dur=<ms> on a request that waited for its rate limit.

The empty 404 carries none of the headers on this page. See The empty 404.

Headers browsers cannot send#

A browser page served from another origin cannot send Authorization, Terse-Key or Terse-Idempotency-Key to the service, and cannot use DELETE, because the service's cross-origin policy does not allow them. Call the service from server-side code.