Craton documentation
Build on Craton.
Open catastrophe models, the data behind them and tools for your exposure, over plain HTTP. Every block marked Runs in CI is executed against the live environment.
QuickstartYour first API call in a few minutes, with no SDK and no approval to wait for.Run a modelNine open catastrophe models in the browser, on your own locations.The open schemaThe data formats the API reads and writes, as JSON Schema. No account or key needed.
Getting started
Your first API call, and the ways to start without a terminal.
- Craton quickstartTen 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.
- Craton for AI agentsYou may be an agent working for an underwriting team, a program designer, a broker, a corporate risk manager, or for a developer building for one of them. This page is written for you. It is short on ceremony and exact about requests, because the two things visiting agents most often lose time to are guessing hosts and guessing request bodies.
- The open schemaThe canonical risk object is Craton's core primitive, and its JSON Schema is open. You can fetch it, read it, validate against it and build on it with no Craton account: nothing to authenticate, nothing to install, nothing that expires. The engine is paid; the vocabulary is not.
Models
The open models you can run, what each result means, how to build your own, and how to list one you run on your own Oasis platform.
- Lab metrics: what each figure in a lab result meansEvery result from the model lab's insurance lanes carries a metrics block (schema lab-metrics/1) beside the fields older clients read. This page says what each figure is, in the terms an underwriter or a catastrophe modeler uses, how the lab computes it, and what it cannot tell you. The lab is at https://lab.oncraton.com; how to submit a run is in the agent walk. Every lab model is an open model, run as its authors published it on fixed inputs. Craton has not validated it.
- Historical earthquakes: a real ShakeMap over your placesThe model lab's openquake-shakemap lane answers one question: what would the shaking of a real earthquake do to your places today? It takes the USGS ShakeMap of one of ten historical earthquakes, the map of how hard the ground shook, built from that earthquake's seismic recordings and felt reports, and runs it through the OpenQuake engine over your schedule. Every lab model is an open model, run as its authors published it on fixed inputs. Craton has not validated it. How to reach the lab is in the agent walk; what each figure means is in lab metrics.
- Europe and Turkey earthquake: the ESRM20 laneThe model lab's openquake-esrm lane gives an annual earthquake loss view for Europe and Turkey from the European Seismic Risk Model 2020 (ESRM20), run in the OpenQuake engine. For each place you send it returns the average annual loss, the occurrence and aggregate loss at return periods up to 1 in 1,000, tail value at risk, and how much the sample itself moves those figures. How to submit a run is in the agent walk; the metrics block shared by every lane is in Lab metrics. Every lab model is an open model, run as its authors published it on fixed inputs. Craton has not validated it.
- Windstorm through Oasis: the PiWind lane, with insured and net lossesThe model lab's oasis-piwind lane runs PiWind, the reference windstorm model of the Oasis Loss Modelling Framework, over the places you send. It always gives ground-up losses. Send policy terms and reinsurance with the spec and Oasis's own financial module adds two more views of the same simulated years: insured losses and losses net of reinsurance. How to submit a run is in the agent walk; every figure's meaning is in Lab metrics. Every lab model is an open model, run as its authors published it on fixed inputs. Craton has not validated it.
- Hazard-map lanes: river flood, coastal flood and wildfireThree model-lab lanes answer from published hazard maps instead of an event set: for each of your places they read the mapped flood depth at every published return period, or the mapped annual burn probability, and say what that means for the value you send. They are fast (seconds for a schedule of thousands of places) and they are only as good as the maps. This page says which maps, how a depth becomes a loss, how the average annual loss is built from return periods, and what these lanes cannot tell you. How to submit a run is in the agent walk; the metrics block shared by every lane is in Lab metrics. Every lab model is an open model, run as its authors published it on fixed inputs. Craton has not validated it.
- Composing a modelFifteen minutes, one terminal, no SDK. By the end you will have composed a parametric rainfall trigger model out of platform primitives, watched Craton backtest it over forty years of pinned public data, read its auto-generated model card, and used it to produce a technical price for a structure.
- The model exchange: models other people runThe model exchange lists catastrophe models that their providers run on their own Oasis platform. You run a listed model from the model lab the same way you run one of Craton's own, and its results open on the comparison page beside every other run. Craton never holds the provider's model files and never takes or passes on money: a listing is either free to run, or run only by the accounts its provider grants.
Triggers
Parametric triggers over public data: define the index, then backtest it over every year of the record.
- The trigger objectA parametric structure pays on a measurement, and trigger is the block where that measurement is written down: which pinned feed is read, what is measured in it, over what window, and what fraction of the limit each level pays. It is the one block nothing else can supply (a schedule of buildings does not carry it, and Craton will not invent it), so POST /objects/{id}/price refuses an object without one.
- The track-gate structureA gate drawn on the map, over an archive of whole storms. This page is the third parametric shape Craton prices: a parametric_index trigger that names a pinned best-track storm archive instead of a daily series, with the gate written in peril.region and the ladder written in the archive's own unit. By the end you will have a complete Gulf-of-Mexico gate object, its 175-season history, and a technical price for it, all from one block.
- Backtest a structureForty years of history for a parametric structure, over HTTP, in one block. Read the quickstart first: it explains the two values you export (CEDE_BASE_URL, CEDE_API_KEY), how to get a key from POST /signup, and the job pattern every Craton verb answers with.
Data
The public datasets behind every result, and the hazard at a location.
- Feeds: the data that is pinned, and how to check itEvery number Craton produces comes out of a pinned snapshot: a dated copy of a public publisher's response, committed to the build with the SHA-256 of its bytes. A price, a backtest and a model run read those files and nothing else, which is why a result replays byte for byte a year later.
- Point hazard lookup: what the pinned data says about a coordinateGET /hazard, with peril, lat and lon in the query, answers one question (what has happened at this place, in the record Craton pins) and answers it synchronously. There is no object to create first and no job to poll: a coordinate goes in, a hazard metric comes out, and the response names the exact snapshot it was computed from.
- Events: the hazard record behind a resultA backtest tells you six years paid and names the events it paid on. This page is where those names come apart into the record itself: the catalog Craton read, the exact solutions that qualified, and the rule that collapsed several of them into one occurrence.
- The storm-report boxHail, thunderstorm wind and tornadoes, priced off the reports people made of them. This page is the fourth parametric shape Craton prices: a parametric_cat_in_a_box trigger that names a pinned storm-report extract instead of an earthquake catalog, with the box written in peril.region and the ladder written in the report's own unit. By the end you will have a Dallas-Fort Worth hail object, its thirty-year history, and a technical price for it, all from one block.
- Wildfire, by the acreA wildfire trigger priced off the fires that were mapped. This page uses the same model as the storm-report box, a parametric_cat_in_a_box trigger over a pinned extract, with the box written in peril.region. Here the extract is MTBS's mapped wildfires and the ladder is in burned acres. By the end you will have a wildfire object for the country around Paradise, California, its forty-one-year history, and a technical price for it, all from one block.
- Grid outage, by the countyA grid-outage trigger priced off how many of a county's electricity customers were without power. The page uses the station-index model, the same parametric_index trigger that prices a rain gauge or a river gauge, over a pinned county outage series from Oak Ridge National Laboratory's EAGLE-I. By the end you will have a Harris County (Houston) outage object, its history since 2018, and a technical price for it, all from one block.
Exposure data
Turning the spreadsheet you have into locations, values and codes a model can use.
- What Ingest survives, flags and refusesThe honesty exhibit: what Ingest reads, what it admits it guessed at, and what it will not read at all, measured on the golden corpus rather than described. Every number below is computed from the corpus manifests and the pinned oracle outputs by tests/unit/test_honesty_exhibit.py, which re-renders this page and fails the build if a single figure has moved. Nothing here is typed by hand, and nothing here is a target: it is a measurement of what Craton does with the ugliest files we could find.
- Exposure coding: OED codes for messy rowsPOST /exposure-codes takes the rows of a schedule of values as plain text, one building a row, and answers with OED 5.0.0 OccupancyCode and ConstructionCode values for each. Every field comes back with its confidence and whether it cleared the gate. A field below the gate is not coded: its row is marked for a person to look at, with the proposal beside it.
- Multi-building rows: find the rows to splitPOST /multi-building-flags takes the rows of a schedule of values as plain text and answers, for each row, whether it describes more than one separate building. A row such as "Bldgs A-D, garden apts" or "Main campus: 3 dorms, library, gym" puts every one of those buildings on one point, with one construction and one height, and a catastrophe model run on it inherits that. This route finds those rows so you can split them before you model.
- Geocoding: from an address to a point you chooseGET /geocode, with q in the query, turns an address or a place name into a short list of candidate points. You read the list and pick one. Every candidate says how precise it is and which public geocoder produced it, so a point in the middle of a street is never passed off as a building.
- Accumulation across a set of objectsPOST /accumulation takes a set of your own canonical objects and answers the three questions a book raises once it is more than one file: how much sits behind each peril, how much sits in each region you declared, and where the value is concentrated. It answers synchronously: the numbers come from the exposures already stored on those objects, so there is nothing to compute against and nothing to wait for.
- Analyse an object: the pinned record, at your own exposurePOST /objects/{id}/analyse runs named analyses over a canonical risk object and records what they found on that object's provenance. It is a job: the call returns 202 with a job id, you poll GET /jobs/{id}, and the finished job carries the artifacts.
Reference
Every error code, how billing works, and how long onboarding takes.
- Craton error referenceEvery refusal the API makes has one shape, whatever route made it and whatever went wrong. This page is the specification of that shape: the envelope, every field in it, every code Craton reports, and the rules that say what can change under you and what cannot.
- Usage, and cancelingOne block, one terminal, no key in advance. By the end you will have read what an account has used in the units Craton bills in, canceled its plan self-service, and seen that the record of what was used survives the cancellation.
- The two measured walksTwo of this product's own production checks are stopwatches, and their budgets come from the operating brief rather than from anybody's judgment: a stranger gets from the published documentation to a first authenticated call in under ten minutes, and from the published documentation to a technical price out of a model they composed themselves in under fifteen.
Legal
The terms an account is created under, and the terms for listing a model on the exchange.
- Craton terms of serviceTerms for Craton, the risk-analytics platform. They say what the software does, what you may expect of it, what it costs, and what happens to the data you send. Read them with the acceptable-use page, which holds the rules of use these terms refer to.
- Craton acceptable useThe rules of use for Craton: what the platform is for, what it must not be used for, and what happens when a rule is broken. It is the companion to the terms of service, which refer to this page rather than restating it.
- Terms for model providersThese terms apply when you list a catastrophe model on Craton's model exchange. They sit alongside the terms of service and the acceptable-use page, which apply to your account as to any other. Where they differ, these terms govern your listing. How to list a model is on the model exchange page.
Being retired
Technical pricing, submission packs and monitoring covers in force. These still work for existing integrations, but Craton is moving away from them.
What Craton prices today
- Parametric earthquake, against a pinned quake catalog.
- A station-measured rainfall, wind or river-flow index, against pinned daily series. The wind ones include named-storm (
tropical_cyclone) structures; the river-flow one carriesfloodagainst a gauge's daily mean discharge. - A track gate for the same named-storm peril, paying on the season's highest best-track wind inside a region you draw, against pinned storm archives for the Atlantic, both Pacific basins, the North Indian Ocean and the southern hemisphere.
- A storm-report box for
severe_convective_storm, paying on the year's largest hail, thunderstorm wind or tornado report inside a box you draw, against pinned NOAA storm reports for six US metros. - A wildfire box on the same model, paying on the year's largest mapped fire by burned acres inside a box you draw, against pinned MTBS fire records for five western US regions.
- A grid outage index on a county's count of electricity customers without power, against pinned EAGLE-I records for ten US counties.
Craton has no pricing model for cloud_outage or extratropical_cyclone (European windstorm), though both are in the canonical object's peril vocabulary. The whole table says what each priced structure declares and how far the pinned data reaches.
- A technical price, from nothingOne terminal, no key in advance. By the end you will have an account of your own, a complete parametric object, and a technical price for it with every assumption behind the number attached to the same response.
- Monitor: record a structure in force, then read the measurementPOST /structures/{id}/monitoring records that a structure is in force. GET /monitoring and GET /monitoring/{id} read the measurement back, and recompute it every time you ask. POST /monitoring/{id}/webhooks has the measurement delivered to an address of yours when it moves, and GET /monitoring/{id}/webhooks shows you every delivery that was attempted.
- Package: the submission pack, as a set of draft exhibitsYou have priced an object and backtested a structure cut from it. This page is where those runs become one document you can hand to a person: an exposure summary, the technical price with its complete assumption set, the backtest behind it, and a draft slip laying the terms out the way a reader expects to meet them: assembled, addressable, and watermarked DRAFT on every page.
- One run, and every receipt behind itA number is worth what its working is worth. This page takes one real price run (made on 2026-08-12 against the environment Craton deploys to) and puts the whole of it in public: the run id, the complete assumption set, the data vintage the number was computed from, and a block you can run that reproduces that recorded receipt byte for byte.
For agents and scriptsllms.txtagents.mdschema.json