This page as Markdown, byte for byte: /quickstart.md

Craton quickstart#

Ten minutes, one terminal, no SDK. By the end you will have turned a location schedule into a canonical risk object — the machine-readable primitive everything else in Craton is built on — and read it back over the API.

Everything you need is on this page. Copy the block, run it, read the rest afterwards if you like.

Which perils this build prices today#

Read this before you plan an integration, because it is the limit most likely to stop one: Craton's canonical object names eight perils and this build prices three of them. Ingest normalises a schedule carrying any of the eight, and the schema is versioned and open and carries all eight. Price runs two parametric models, and a structure outside both is refused by name — a job that ends failed carrying 422 unpriceable_object — rather than handed a number no model stands behind.

A no is a missing model, not a missing route. Ingest reads a wildfire schedule, POST /objects stores a flood object — both are valid canonical objects — and POST /accumulation rolls a set of any perils up, naming for each one the pinned vintage a hazard question about it would be answered against, or the absence of one. What a no costs you is the technical price and the backtest under it, and the hazard readings behind them: GET /hazard answers point lookups for earthquake, tropical_cyclone and weather_station, and names the peril it holds no pinned feed for rather than guessing at it.

A "yes" prices only where the data is pinned. Both models read a feed vintage this build already holds, because a result that replays byte for byte cannot fetch anything at price time — and every pinned feed is one box or one grid point: a quake catalogue over a single region, daily rainfall and wind series at single points. The pinned data feeds is the list, and GET /feeds is that same list from the deployment you are pointed at. A risk somewhere the pinned feeds do not reach cannot be priced here yet, whatever its peril.

Both models, what each one reads, and how each refusal reads, are on A technical price, from nothing. None of this is a limit of the canonical object: an object for any of the eight perils is valid and storable today, and the peril vocabulary grows only by a schema version bump.

What you need#

• curl 7.76 or newer (this page uses --fail-with-body) and python3. Nothing else — no SDK, no package to install.
• CEDE_BASE_URL — the base URL of the Craton environment you are pointed at.
• An API key for that environment — and you do not need one in advance. If CEDE_API_KEY is unset, the block below signs you up and issues one, in the same run, before it does anything that needs it.

Craton is pre-release. The environment you can reach today is staging:

export CEDE_BASE_URL="https://altier.ridgehead-hamlet.ts.net:8472"   # no trailing slash
export CEDE_API_KEY="…"              # optional: leave it unset and sign up below

Staging is reachable to members of the operator's tailnet, not to the open internet — a public sandbox on its own name is waiting on a domain. If you cannot reach the URL above, ask whoever pointed you at this page for access, or point CEDE_BASE_URL at any environment someone runs for you. Nothing else on this page changes either way: the quickstart only ever speaks HTTP to $CEDE_BASE_URL, so a sandbox on someone's desk, staging, and the hosted environment to come all behave identically from here.

Getting a key: POST /signup#

Signing up is self-service and takes one unauthenticated call. No invitation, no approval queue, no email round trip, no payment details — nothing on this path waits for a human, here or at our end. Creating an account means you agree to the terms of service and the acceptable-use policy; both are short and both are served on this site.

curl -sS --fail-with-body \
  -H "Content-Type: application/json" \
  -d '{"label": "quickstart"}' \
  "$CEDE_BASE_URL/signup"

201 and an account on the free sandbox plan, holding its first key:

{
  "schema_version": "0.1.0",
  "id": "acct_9f4c1e0b7a2d5c38",
  "created_at": "2026-08-11T02:33:54.512907Z",
  "plan": "sandbox",
  "label": "quickstart",
  "api_key": {
    "id": "key_3b71c0d94e26af58",
    "secret": "cede_sk_…",
    "created_at": "2026-08-11T02:33:54.512907Z",
    "scheme": "Bearer",
    "expires_at": null
  }
}

api_key.secret is the value you export as CEDE_API_KEY. Keep it when it prints. Craton stores only its digest, so that response is the one and only place the secret ever exists on our side: no later call returns it, nobody can look it up for you, and a lost secret means signing up again. The body is optional — curl -X POST "$CEDE_BASE_URL/signup" with nothing in it works identically; label is just a name you will recognise the account by.

How long the key lasts: indefinitely. expires_at is null and that is the only value this build issues — there is no time-to-live, no session, no refresh call and no age at which a key stops working. Write it into your environment file and leave it there. Two consequences worth having in advance, because they are what a 401 on a key that worked five minutes ago actually means:

• A key survives a redeploy of the environment that issued it. Staging redeploys whenever the code moves, and keys, accounts, objects, jobs and usage are held in a database across it.
• So a 401 is about the credential that arrived, not about time. The usual cause is a shell variable that lost its value between one command and the next — -H "Authorization: Bearer $CEDE_API_KEY" with CEDE_API_KEY unset sends the scheme and no key, and the response says so in those words.

Your key goes in an Authorization: Bearer … header on every call except GET /health and POST /signup — the two routes that answer without one, because one tells you the environment is up and the other is how you get a key at all. There is no other authentication scheme and no unauthenticated data route.

The whole thing, in one block#

Run this in an empty directory. It signs you up if you have no key yet, writes one CSV, sends it, waits for the job, and prints the risk object that came back. CEDE_BASE_URL is the only thing it needs from you.

set -euo pipefail

: "${CEDE_BASE_URL:?export CEDE_BASE_URL first — see 'What you need'}"

# Read one field out of a JSON document on stdin: `field a.b.0.c`.
field() {
  python3 -c 'import json, sys
document = json.load(sys.stdin)
for step in sys.argv[1].split("."):
    document = document[int(step)] if step.isdigit() else document[step]
print(document)' "$1"
}

# 1 — Is this environment serving? /health answers without a credential.
curl -sS --fail-with-body "$CEDE_BASE_URL/health" | field status

# 2 — A key, if you do not have one. /signup is the other route that needs no
#     credential: it creates an account on the free sandbox plan and issues its
#     first key, with nobody in the loop. The secret is shown here and nowhere
#     else, so save what this prints if you want to reuse the account.
if [ -z "${CEDE_API_KEY:-}" ]; then
  account=$(curl -sS --fail-with-body \
    -H "Content-Type: application/json" \
    -d '{"label": "quickstart"}' \
    "$CEDE_BASE_URL/signup")
  CEDE_API_KEY=$(printf '%s' "$account" | field api_key.secret)
  export CEDE_API_KEY
  printf 'signed up: %s on the %s plan\n' \
    "$(printf '%s' "$account" | field id)" \
    "$(printf '%s' "$account" | field plan)"
  printf 'your key (shown once): %s\n' "$CEDE_API_KEY"
fi

# 3 — A location schedule. Two rows, written here so you need no file from
#     anywhere else. Craton reads far uglier spreadsheets than this one.
cat > schedule.csv <<'CSV'
Location ID,Address,Latitude,Longitude,Occupancy,Construction,Year Built,Building,Contents,Peril
LOC-0001,"2-16-1 Konan, Minato-ku, Tokyo",35.6284,139.7387,Warehouse,Reinforced Concrete,2011,"¥8,400,000,000","¥2,600,000,000",Earthquake
LOC-0002,"1-1 Soga, Chuo-ku, Chiba",35.5687,140.1247,Light Industrial,Steel Frame,1998,"¥5,100,000,000","¥900,000,000",Earthquake
CSV

# 4 — Ingest it. First call that needs your key. It answers 202 and a job:
#     every Craton verb answers with a job, never with the answer itself.
job_id=$(curl -sS --fail-with-body \
  -H "Authorization: Bearer $CEDE_API_KEY" \
  -F "[email protected];type=text/csv" \
  "$CEDE_BASE_URL/ingest" | field id)
echo "ingest job: $job_id"

# 5 — Poll the job until it stops moving.
state=unknown
for _ in $(seq 1 150); do
  job=$(curl -sS --fail-with-body \
    -H "Authorization: Bearer $CEDE_API_KEY" \
    "$CEDE_BASE_URL/jobs/$job_id")
  state=$(printf '%s' "$job" | field status)
  case "$state" in succeeded|failed) break ;; esac
  sleep 0.2
done
if [ "$state" != succeeded ]; then
  printf 'ingest did not succeed: %s\n' "$job" >&2
  exit 1
fi

# 6 — Read back the canonical risk object the file became.
object_path=$(printf '%s' "$job" | field result.objects.0.links.self)
curl -sS --fail-with-body \
  -H "Authorization: Bearer $CEDE_API_KEY" \
  "$CEDE_BASE_URL$object_path" > object.json

python3 -m json.tool object.json
echo "done — your first risk object is at $object_path"

If the last line printed, you are through. If something went wrong, jump to When it does not work.

What just happened#

**GET /health** — reports the build that is running, which verbs it serves, and — in its discovery member — the addresses that list what it holds: GET /feeds for the pinned data snapshots and GET /primitives for the model builder's vocabulary. So a load balancer, a deploy script or a nervous human can ask "is this thing up?" without holding a credential, and a client can find where to start without reading this page.

**POST /signup** — the way in, and the other route served without a key, because a route that needed a key to get a key would need a human to break the circle. It creates an account on the free sandbox plan and issues that account's first key, live for the very next request — no restart, no propagation delay, no waiting. Objects, jobs and usage belong to the account, so a second signup is a second tenant that cannot see the first one's work. GET /account reads back the account your key belongs to; it never returns the secret, because Craton does not have it.

**POST /ingest** — file in, job out (202 Accepted, with the job's address in the Location header). Ingest normalises: it decodes the file, works out which column meant what, parses money and coordinates, and emits canonical risk objects. It does not enrich, guess quietly, or discard what it could not read — see source_fidelity below.

The request is multipart/form-data with the file in a part named file — that is what -F "[email protected];type=text/csv" builds above, and posting the file as the whole request body answers 415 saying so. What the part may declare is the next table; it is checked rather than believed, and anything else answers 415 unsupported_media_type before a job exists.

The form takes one other part, and it is optional: **currency**, an ISO 4217 code such as USD. Send it only for a schedule that names no currency of its own — no USD in a column header, no $ in any cell. Ingest never infers a currency (reading USD off a State column saying FL is enrichment, which is Analyse's job and not this one), so without this part such a file's amounts come back untagged and ambiguous_rows says so. With it, exposure.currency and every value carry the code you gave, and guessed_units records that it came from your request rather than from the file — a difference a reader of the object should be able to see. If the file does state a currency and it is not the one you sent, the job fails with 422 currency_conflict naming both: Ingest will not overwrite the file, and will not ignore you. The job echoes what you declared back at subject.declared_currency, so a client holding only the job id can still say what it sent — the same reason subject.source is there.

curl -sS --fail-with-body -H "$auth" "$CEDE_BASE_URL/ingest" \
  -F "[email protected];type=text/csv" -F "currency=USD"

Ingest v0 reads delimited text (comma, semicolon, tab, pipe) and JSON Lines, so those four rows are the whole of it. A declared type is a claim, never a finding: the media type the reader actually read the bytes as is written onto the object it produced, at provenance.source_files[].media_type, and a file whose declaration was plausible but whose bytes are not readable is refused on the job with unsupported_source.

A 202 is not a statement that your file is readable#

POST /ingest answers 202 for every request it can accept at the door — and that includes a file it will turn out to be unable to read. Two kinds of fault reach this route, and one rule decides where each is answered: can it be known without reading the file?

Everything in the top half is a fact about the request, knowable before a single byte of the file is looked at, so it is answered before a job exists. Everything in the bottom half is a fact about the bytes, and finding it out is the ingest work — decoding the file, looking for a delimiter, finding the header under the preamble. POST /ingest never does that work, so it has no answer to give.

The consequence, stated plainly because it surprises people: post a file of prose (This is not CSV) declaring Content-Type: text/csv, and you get 202 and a job id, not a 4xx. Poll the job and it is failed, carrying 415 unsupported_source and a message saying no delimiter occurs anywhere in the file. The status is the same one a synchronous refusal would have carried, in the same shape — it just arrives on the job, because that is where it was discovered. **Always poll the job. A 202 means "accepted for reading", never "read".**

**GET /jobs/{id}** — every verb runs as a job and moves through queued → running → succeeded | failed. Ingest is fast, so you will usually see succeeded on the first poll; write your client against the states anyway, because a verb that reads forty years of history will not answer on the first one. A job that fails carries an error object in the same shape a synchronous refusal would have had — a failure is a job state, not a dropped connection.

**GET /objects/{id}** — the canonical risk object. Objects and jobs belong to the key that created them; another key gets a 404, not a 403, because the existence of your objects is itself yours.

The parts of the object worth looking at first#

exposure.locations[]      each row, normalised: ref, address as given,
                          decimal coordinates, occupancy, construction,
                          year built, and values per coverage part
exposure.values           the schedule's totals, summed per coverage part
exposure.currency         read from the money it actually parsed, or the
                          code you declared on the request for a file that
                          states none. Absent when neither happened — the
                          amounts are still there, just untagged, and
                          ambiguous_rows says so
peril.code                from the closed peril vocabulary — "Earthquake"
                          in the file became "earthquake" here
provenance                the source file's name, its sha256, and the id of
                          the ingest run that produced this object
status                    "draft": exposure and peril, no structure yet

**exposure.source_fidelity is the part to read second, and the reason to trust the first.** It is Craton's honesty channel, and it is always present:

• unmapped_columns — columns Craton did not recognise, each with a sample of the values it left behind. Empty in the run above; add a column called Notes to schedule.csv and re-run to watch it fill.
• guessed_units — every place a unit was inferred rather than stated.
• ambiguous_rows — rows that could be read more than one way.

Nothing is dropped silently. If a column did not make it into the object, it is named here.

Where to go next#

• Finish the object. PATCH /objects/{id} writes onto the object you just ingested the things the file could not tell Craton: which peril the cover is against, the limit and attachment, the trigger that decides the payout, and the period. Ingest emits exposure — and a peril only when the file named one in words, as the schedule above did — because normalisation is all it promises (SPEC §3.1); everything else is a decision you make after reading the file, and this is where you record it. Send only the blocks you are writing; each one replaces the block of that name whole, so a financial_structure arrives complete rather than merged into a half-remembered one. It writes those six blocks and refuses the rest: the id and schema version are the server's, status is what the object has rather than what you assert, provenance only ever grows, and exposure is Ingest's record of a file it read — a different exposure is a different object. *What PATCH /objects/{id} writes, and what it does not* on the price page is the full table, including where each read-only block does come from and what to do when the file did not state the currency. If the object had already been priced and you move something the price was computed from, the old premium comes off and the object goes back to draft, because a premium under a limit it was never computed for is a wrong number that reads exactly like a right one. Price it again; it is one call.
• Price. POST /objects/{id}/price computes a technical price for an object, with its assumptions attached and the model and version that produced it named on the result. It needs an object that carries a financial structure (limit, attachment) and a trigger — so either patch them onto the object you ingested, as above, or send a complete object with POST /objects. That is the third runnable page: A technical price, from nothing signs up for an account of its own, reads it back, posts a complete parametric object and prints the price with the whole assumption set that produced it — and its second block walks the other way in, from a schedule through `PATCH /objects/{id}` to a price on the object the file became. The trigger is the one part of that object no file can carry and Craton will not invent, so it has a reference page of its own: The trigger object is every member of the block field by field — what the schema requires against what the model pricing it requires — and the smallest trigger of each shape that prices.
• Structure and Backtest. There is a second runnable page for these two: Backtest a structure, which builds a complete parametric object, cuts a structure from it and replays it against forty years of the pinned public archive — and whose second block walks the same road from a schedule you were given: ingest it, PATCH /objects/{id} the peril, limit, attachment, index and term onto the object the file became, cut the structure from that, and replay. In short: POST /objects/{id}/structures cuts a candidate structure from an object — the trigger, limit, attachment and term a verb evaluates — and answers with a structure of its own that has an id. Send no body to take the object's own terms, or send the blocks you are varying (trigger, financial_structure, period) to make a variant. POST /structures/{id}/backtest then replays it against the pinned public archive and answers with a job like every other verb; the finished job carries the artifact, and GET /backtests/{id} serves it again at the address in links.self.

The artifact is year by year: every calendar year in the window with what the structure would have paid, the occurrences behind it named by the publisher's own event ids, loss statistics and a burning-cost view, and a data_coverage block naming every year the pinned archive holds no record for — disclosed, never filled in. It is history, not a forecast, and it says so on every copy. Send {"window": {"from_year": 1996, "to_year": 2015}} to narrow it; the default is the archive's full period of record, and a window reaching outside what the archive holds is refused rather than quietly clipped.

Backtest and Price read a structure through the same code, so the burn rate in a backtest is the burn rate underneath the technical price of the same structure — not a second number that happens to look similar.

Two halves of Structure (SPEC §3.4) are here: creating one and reading it back. Revisions, standalone indices and wordings are outside this build, so GET /health lists structure because those two routes answer — route existence, not a finished verb — and backtest, whose routes are all here, on the same rule.

• Compose a model. Composing a model is the same shape of walkthrough for the model builder: pick a feed, a measurement, a transform and a payout function, and Craton validates, backtests and cards the model before it exists. No code — a v1 model is those four primitives and nothing else. It ends with a technical price produced by the model you composed.
• The schema. The canonical risk object is published as JSON Schema and is open source. Validate against it locally, generate types from it, or diff two versions of an object — it is a file, not an API call.

The whole surface, and where it stops#

Craton's specification names seven verbs. This build answers on all seven — Ingest, which you just used, Analyse, Price, Structure, Backtest, Monitor and Package — each on its first slice and no wider, and the sections after the table say where each one stops. Rather than let you find the edge by hitting it, here is the entire route table this build answers on:

That is all of it. There is no other route, and nothing on this page needs one past the first eight. GET /usage and DELETE /subscription are the billing pair: usage is metered per object and per model run, the free sandbox is an allowance of units rather than a trial that expires, and cancelling is self-service and immediate — after it, metered verbs answer 402 account_cancelled and nothing further is recorded. Everything to do with payment itself lives at the payment processor, in test mode; Craton holds no money and no card. Those two have their own runnable page as well, Usage, and cancelling, which reads an account's usage, cancels its plan and reads the usage back afterwards. The four structure and backtest routes have their own runnable page, Backtest a structure; the two account routes and the price route have theirs, A technical price, from nothing; the four registry routes have theirs, Composing a model — a registry surface rather than one of the seven verbs, whose models produce an index and a technical price under exactly the same rules as a platform model. The two event routes have theirs, Events: the hazard record behind a result, which reads the catalogue a backtest paid on and takes one of its events apart into the occurrence behind it. The three feed routes have theirs too, Feeds: check the data a result was computed from: a price and a backtest name the id, the version and the SHA-256 of the data they read, and that page walks from those three strings to the bytes themselves and recomputes the digest.

Two lines of that table carry two methods each: /objects/{id} answers GET to read an object and PATCH to write onto it, and /monitoring/{id}/webhooks answers POST to register an address and GET to read the registrations and their delivery logs back. So the thirty-two rows are thirty-two addresses and thirty-four route entries. Every other address answers one method.

**32 routes, and GET /health names seven verbs — Ingest, Analyse, Price, Structure, Backtest, Monitor and Package — one for every verb this table has an address behind, and no others.** That is a checked invariant, not a coincidence of editing: on every change to Craton, a gate reads the verbs a running server returns against that server's own route registry and fails in both directions, so the list can neither invent a verb this build has nothing behind nor drop one it answers on. It used to trail the surface — Backtest answered for a day while verbs still said Ingest and Price — and that is the gap the gate closes.

A route answering is not the same as a job you can finish, so a second gate checks the harder half: it signs up holding no key, ingests a schedule, writes the terms onto the object, looks up the hazard at one of its locations, reads the event catalogue behind its peril, prices it, cuts a structure and backtests it, and assembles the submission pack for it — every step a call you could make from this page — and fails if any verb in verbs was not carried all the way to a finished result. A name in that list is therefore something a stranger has reached, not something a route table allows.

Read a name in verbs as reachable, not complete: structure is there because two of its routes answer, while revisions, /indices and /wordings are outside this build, and analyse is there because the point hazard lookup, the event catalogue, the footprint route, the analyse job over an object and the accumulation rollup all answer. monitor is there because a structure can be recorded in force and read back as a measurement, and a webhook can be registered on the record and read back with its delivery log. The four registry routes are counted in the thirty-two but appear in the response's registry member, not verbs — a registry surface rather than one of the seven. The two billing routes are counted there too and appear in neither member: what an account owes is not a capability of the engine. A name in registry is a surface, not an address, which is why discovery sits beside it and gives the two catalogue routes — /feeds and /primitives — as paths a client can call: the builder's vocabulary used to be findable only from a page like this one (CEDE-187), and now the health document itself points at it. Write your client against the routes; read verbs to learn which of the seven a deployment reaches at all.

Where Structure stops. Two halves of it are here: cutting a structure from an object, and reading one back. Revisions, standalone indices and wordings are outside this build, and POST /objects above remains the way to bring a complete structured object in as JSON.

Where Analyse stops. It does not stop: every route the specification names for it answers here. GET /hazard answers what the pinned public record holds at a single point, synchronously and with the snapshot it read named in the answer — the point hazard lookup is the page for it. The public event catalogue and event footprints are two more routes above, with their own page, Events: the hazard record behind a result. POST /objects/{id}/analyse runs those same two readings over an object — at its own coordinates, for the peril it carries — and records the artifacts on its provenance, which is Analyse an object. POST /accumulation rolls a set of your own objects up into exposure per peril, per declared region and by concentration — Accumulation across a set of objects is its page.

Where Monitor stops. Its first slice is here: record a structure as in force — your own assertion about a transaction executed entirely outside Craton — and read its index against the newest pinned snapshot, with the distance to attachment on every read. Monitor a structure is the page for it, and it is worth reading for one thing in particular: a term ahead of the pinned record measures nothing, and says so, rather than reporting a zero. Webhooks have no address in this build. When a level is reached, Craton reports the measurement and nothing that follows from it.

Where Package stops. POST /objects/{object_id}/package assembles a submission pack from the runs an object already carries, and GET /packages/{package_id} serves it back — the exposure summary, the pricing exhibit with its complete assumption set, the draft slip restated from the object's own terms, and the backtest exhibit when a backtest of a structure cut from that object is recorded. Every document in it is watermarked as a draft produced by analytics software, the slip included, and nothing in the pack signs, accepts or executes anything. Package: the submission pack is the page for it. An object that cannot fill the slip is refused with the missing blocks named, rather than handed a slip with blank sections.

Every verb this build serves is above, and each stops where its section says. No verb SPEC names is missing an address now, so this page has no list of the unbuilt — what it has instead is the boundary of each slice, stated where you meet it.

Do not take any of that on trust, and do not take it as permanent either — ask the environment you are pointed at, because it answers for itself:

curl -sS "$CEDE_BASE_URL/health"

Read three members of it. verbs is the seven of the specification this build reaches. registry is the model-builder surfaces beside them. discovery is the two addresses that list what this deployment actually holds — GET /feeds for the pinned data snapshots, GET /primitives for the feeds, measurements, transforms and payout functions a model is composed from — each with a sentence saying what it lists, so a client can walk from "the service answered" to the vocabulary it can build with without reading a page first. Nothing in it needs this page: point your own code at /health, follow discovery, and you have the same two catalogues.

The verbs member of that response is checked against the server's own route registry on every change, in both directions, and against a walk that starts at POST /signup and finishes a job for every verb it names, so it is the list of what that deployment really serves — no more and no less — at the moment you ask. A verb that appears there has been called end to end from a fresh signup; one that does not is not built there yet, whatever any page says. When one lands it will run behind the same job pattern you already used — POST to start it, GET /jobs/{id} until it stops moving — so the client you wrote above is the client you will keep.

When it does not work#

Every refusal has the same shape — status, code, message, and sometimes details — and validates against the published error schema. Including the ones nobody predicted: a 500 is a structured document too.

The table above is the short list. The error reference is the full one: the envelope field by field, every code this build reports and the status it arrives with, the same shape as it appears on a failed job, and the rules saying what can change under a client and what cannot. Read it once and write your failure path once.

The block on this page is extracted verbatim and executed against a live environment on every change to Craton. If it stopped working, the build stops too — these instructions cannot quietly drift away from the product.