Chronum API
Interface version 2026-10-29, build 0.12.2. Base address https://chronumapi.com. Generated by the server from its own route table and frozen response shapes.
About
What this is
Chronum is an evidence-linked, append-only record of historical events: what happened, when, where, who was involved, what sources say, and how sure anyone is. Every write adds a row; nothing is ever updated or deleted. A change is a new version of the same record, and every version stays readable.
Versioning
The interface is versioned by date. Responses carry the date in meta.api_version and in the Chronum-Version header. The shape of every documented response is frozen for that date and checked by an automated suite on every deploy; a breaking change gets a new date, never a silent edit.
One response envelope
Every answer is JSON with the same envelope: {"ok": true, "data": {...}, "meta": {...}} on success, {"ok": false, "error": {"type", "code", "message"}, "meta": {...}} on failure. meta always carries request_id (quote it when reporting a problem), api_version, build and server_time.
Keys and scopes
Public reads need nothing. Writes need an application key sent as Authorization: Bearer ck_live_... . Only a fingerprint of the key is stored; the key itself is shown once when it is issued. Scopes: submit (write your own records), review (change truth status, confirm groupings, accept evidence), admin (run the key queue), and key, which every valid key carries and which is all you need to see, rotate or revoke your own keys. Third parties ask for a key through the key request addresses below; a person approves every request.
Visibility
Every record has a visibility, separate from its truth status: public (anyone), registered (any key holder), circle (people the owner named), owner (only the owner). Reviewers and admins see everything so that review is possible. A record you may not see answers 404, not 403, so that private ids are not confirmed.
Truth status and review
Truth status (draft, submitted, supported, disputed, retracted) moves only through a signed review. Owners cannot approve their own records, reviewers cannot review their own, and a retraction needs a written reason that stays visible. Retracted records remain addressable: history is corrected, never erased.
Changing a record
To change a record, POST to its /versions address with the fields to change, a change_reason, and optionally expected_version (409 if someone else changed it first). Unknown fields are refused with 400 unknown_field. Every version records who wrote it and through which application.
Paging
List addresses return records in the order of their latest change and take limit (1 to 100, default 25) and cursor (the next_cursor from the previous page). Cursors are stable because rows never change; a record that gets a new version moves to the end. q filters by text (2 to 100 characters, case-insensitive; % and _ are taken literally). Records written by the automated contract test suite are left out of lists, search and the change feed; they remain readable at their own address.
Limits and browsers
Requests are limited per minute: 60 for callers without a key (per connection address, of which 20 may be writes), 600 per key (of which 120 may be writes), and 600 in total from any one address. Over a limit the answer is 429 too_many_requests with a Retry-After header and retry_after_s saying how many seconds to wait. Web pages may call the API from a browser only from https://historysnippet.com and https://www.historysnippet.com; every other application calls from its own server. Never put a review or admin key in browser code. Answers to key holders are marked private so that no shared cache keeps them.
Where the service is offered
Chronum is not offered where a legal right to be forgotten conflicts with an append-only record (the European Union and European Economic Area, the United Kingdom and crown dependencies, Switzerland). Callers from those regions receive 451 region_not_served. The country is decided on this server from the caller's connection address using the DB-IP Lite country database (db-ip.com), used under the Creative Commons Attribution 4.0 licence. This page and the health address are never blocked.
curl https://chronumapi.com/v1/events?limit=3
curl -H "Authorization: Bearer ck_live_..." -H "Content-Type: application/json" \
-d '{"title":"First powered flight","summary":"Kill Devil Hills, 17 December 1903","visibility":"public"}' \
https://chronumapi.com/v1/eventsAddresses
72 addresses. Scope read:public means no key is needed.
Service
Status and reference frames.
| Method | Address | What it does | Scope |
|---|---|---|---|
| GET | /v1/health | Service status: database, schema migration number, build, region policy dataset in use. Never blocked. | read:public |
| Method | Address | What it does | Scope |
|---|---|---|---|
| GET | /v1/timeframes | The time reference frames the server knows (Gregorian UTC, Julian calendar, astronomical year, years before present, Mars sol date, mission seconds, and two it cannot convert), each naming the conversion the server applies. | read:public |
| GET | /v1/spatialframes | The spatial reference frames (Earth WGS84, lunar, Martian, vessel-local and more). | read:public |
Events
An event is something that happened. It carries a title, a summary, a truth status, a visibility, and any number of time positions, place positions, claims, media and tags.
| Method | Address | What it does | Scope |
|---|---|---|---|
| GET | /v1/events | List events visible to you, in order of their latest change. status, q (title, summary), limit, cursor. | read:public |
| GET | /v1/events/{id} | One event with its current time positions, place positions and links. | read:public |
| GET | /v1/events/{id}/versions | Every version of an event, oldest first, with who wrote each and why. | read:public |
| GET | /v1/events/{id}/claims | The claims attached to an event that are visible to you. | read:public |
| POST | /v1/events | Create an event. Fields: title (required), summary, visibility, circle_id. Scope submit. | submit |
| POST | /v1/events/{id}/versions | Append a new version of an event: any of title, summary, visibility, circle_id, event_status (reviewers only), retraction_reason; change_reason required; expected_version optional. | submit |
Time and place
Everything recorded is a period, never a moment: a photo lasts its shutter time, a life runs from conception to death. A time position keeps the source's own words, a written form the server can read, and four limits the server works out on one axis (seconds from 1970-01-01T00:00:00Z): the earliest and latest the period could have started, and the earliest and latest it could have ended. A limit nobody knows is open (null). No best-guess point is stored. Place positions name a reference frame (Earth, lunar, Martian, vessel-local) with explicit uncertainty. False precision is refused.
| Method | Address | What it does | Scope |
|---|---|---|---|
| POST | /v1/events/{id}/time | Add a time position to your event. Give time_frame_id, original_value (the source's own words) and written, a form the server can read; the server then works out the four limits (begin_earliest_s, begin_latest_s, end_earliest_s, end_latest_s), records the mark on the source (~ approximate, ? uncertain, % both), the algorithm and its version, and suggests precision_code and certainty, which you may set yourself. Calendar frames take the Extended Date/Time Format: 1903, 1903-12-17, 1903-12-17T10:35:00Z, 1903~, 190X, -0100, Y-65000000, a span A/B (started in A, ended in B; ../B and A/.. open one end), a set [A..B] (sometime between), [..B] (B or earlier), [A..]. Years before present, Mars sol dates and mission seconds take a number or A/B; mission seconds also need epoch; years before present may add plus_minus. Optional duration_s says how long the period lasted. no_date_clues: true stores the widest defensible limits instead. For frames the server cannot convert (cosmological_model, unknown) give the four limits yourself. inside_temporal_position_id borrows the limits of another time position (a photo sometime during a life): the period can start no earlier and end no later than that one could; written and duration_s narrow it further. Also position_role, source_id. | submit |
| POST | /v1/events/{id}/place | Add a place position: spatial_frame_id, body, coordinate_kind, latitude/longitude or coord_x/y/z with uncertainty_m (required for coordinates and more than zero: a point is a small circle), or coordinate_kind named_place with inside_entity_id (a place record; the place's shape valid at the event's time is the limit) and place_label; position_role, source_id. | submit |
| POST | /v1/time/{tid}/versions | New version of a time position (owner of its event, or a reviewer). A new written value is read again and the limits recomputed; every earlier version stays. If other time positions borrow their limits from this one and its limits change, they are flagged for review (meta.borrowers_flagged). Send inside_temporal_position_id null to stop borrowing. | submit |
| POST | /v1/place/{sid}/versions | New version of a place position (owner of its event, or a reviewer). | submit |
Sources
A source is something that can be cited: an original artifact, testimony, scholarship, an institutional summary. Sources are linked to claims as evidence.
| Method | Address | What it does | Scope |
|---|---|---|---|
| GET | /v1/sources/{id} | One source and the claims it is cited by. | read:public |
| POST | /v1/sources | Create a source: title, source_type (original_artifact, contemporary_testimony, later_scholarship, institutional_summary, machine_generated, personal_recollection, other), canonical_uri, creator, publisher, archival_locator, rights_note, visibility. | submit |
| POST | /v1/sources/{id}/versions | New version of a source. | submit |
| GET | /v1/sources | List sources visible to you. source_type, q (title, creator, publisher), limit, cursor. | read:public |
Claims and evidence
A claim is a specific statement about an event (predicate, value, qualifiers). Evidence links a claim to a source with a locator and an excerpt. Reviewers accept evidence and move claims through truth status.
| Method | Address | What it does | Scope |
|---|---|---|---|
| GET | /v1/claims/{id} | One claim with its evidence links and reviews. | read:public |
| POST | /v1/events/{eid}/claims | Add a claim to your event: predicate, object_value, qualifiers (object), visibility. Claims start as draft; submitted is the owner's signal that review may begin. | submit |
| POST | /v1/claims/{id}/versions | New version of a claim: object_value, qualifiers, visibility, claim_status (submitted by the owner; supported, disputed, retracted by review only). | submit |
| POST | /v1/claims/{id}/evidence | Link a source to your claim: source_id, relation (supports, contradicts, mentions), locator, excerpt. Links start proposed. | submit |
| POST | /v1/evidence/{lid}/versions | New version of an evidence link: locator, excerpt, link_status (accepted or rejected by a reviewer). | submit |
| GET | /v1/claims | List claims visible to you. claim_status, predicate (exact code), event_id, q (predicate, value), limit, cursor. | read:public |
Reviews
The only way truth status changes. A review names the subject, the decision (approve, dispute, retract, restore), the policy version applied, and the reviewer.
| Method | Address | What it does | Scope |
|---|---|---|---|
| POST | /v1/reviews | Record a review: subject_kind (event, claim, relationship...), subject_id, decision (approve, dispute, retract, restore), policy_version, notes, retraction_reason when retracting, expected_version. Scope review. You cannot review your own record. | review |
Media
Photos, video, audio and documents are stored in a private bucket. Uploads go straight from the client to the bucket through a signed address; the server re-reads and hashes the bytes on confirmation. Unpublishing or retracting stops the server signing download addresses; the bytes are never deleted.
| Method | Address | What it does | Scope |
|---|---|---|---|
| POST | /v1/media/upload-requests | Ask for an upload address: mime_type, byte_size, original_filename, event_id, visibility, authenticity_class (original_artifact, restored, reconstructed, synthetic_depiction), transformation_note (required for anything not original). Returns a signed PUT address valid 15 minutes and the pending asset id. | submit |
| POST | /v1/media/{id}/confirm | After uploading, confirm with the sha256 you computed. The server checks the stored size, re-reads files up to 100 MB and verifies the hash, then marks the asset stored. | submit |
| POST | /v1/media/{id}/versions | New version of a media asset: visibility, rights_note, authenticity fields, asset_status (unpublished by the owner; retracted by review only). | submit |
| GET | /v1/media/{id} | One media asset. When stored and visible to you, includes a signed download address valid 15 minutes. 410 with the reason when unpublished or retracted. | read:public |
| GET | /v1/media | List media assets visible to you, in order of their latest change: event_id, media_type (photo, video, audio, document, other), asset_status (pending, stored, unpublished, retracted), authenticity_class, limit, cursor. Lists never carry a download address; read one asset for that. | read:public |
Entities and relationships
People, places, organizations, objects, concepts, celestial bodies and vessels, with aliases and outside identifiers. Relationships join entities, events, claims and media with a coded relation. A living private person cannot be made public without a reviewer.
| Method | Address | What it does | Scope |
|---|---|---|---|
| GET | /v1/entities/{id} | One entity with its aliases, outside identifiers and relationships. A relationship is listed only when the record at its other end is also visible to you. | read:public |
| POST | /v1/entities | Create an entity: entity_type, canonical_label, aliases (list), external_ids (object), description, is_living_private_person, visibility, circle_id. | submit |
| POST | /v1/entities/{id}/versions | New version of an entity, including entity_status merged (with merged_into_entity_id) or retracted (review only). | submit |
| POST | /v1/relationships | Relate two records: from_kind, from_id, relation_code (lowercase code such as participated_in, located_at, depicts, part_of), to_kind, to_id, time_bounds_note, source_id. Both ends must be visible to you. | submit |
| POST | /v1/relationships/{rid}/versions | New version of a relationship (its first author or a reviewer). Status changes need the review scope. | submit |
| GET | /v1/entities | List entities visible to you. entity_type, q (label, aliases, description), limit, cursor. | read:public |
| GET | /v1/relationships | List relationships whose BOTH ends are visible to you: from_kind with from_id, to_kind with to_id (an id needs its kind), relation_code, relationship_status (retracted ones are listed only when you ask for that status), limit, cursor. Each row links to both ends. | read:public |
Caret tags
A ^caret tag is a strong hint that uploads belong together (same night, same field). It is never proof and never an identifier. Tags normalize to a lowercase key; assignments can be removed by a new version.
| Method | Address | What it does | Scope |
|---|---|---|---|
| POST | /v1/carettags | Create or find a tag: literal_tag starting with ^. Returns 201 for a new tag or 200 with the existing one for the same normalized key. | submit |
| GET | /v1/carettags/{key} | A tag by its literal or normalized key, with the subjects it is on that are visible to you. | read:public |
| POST | /v1/carettags/{id}/assignments | Put a tag on your record: subject_kind (event, media_asset, flash_group, entity), subject_id. 409 if already on it. | submit |
| POST | /v1/assignments/{aid}/versions | Remove or restore a tag assignment: assignment_status (active, removed), change_reason. | submit |
| GET | /v1/carettags | List caret tags you may know of: a reviewer or admin sees every tag; anyone else sees tags they created and tags on at least one record visible to them. q (part of the tag, with or without ^), limit, cursor. | read:public |
Flash groups
A flash group is the hypothesis that several clips captured the same moment from different viewpoints. Members are proposed by clip owners, confirmed by reviewers, and disputing one needs evidence.
| Method | Address | What it does | Scope |
|---|---|---|---|
| POST | /v1/events/{eid}/flashgroups | Propose a flash group for your event: grouping_rule_note, temporal_tolerance_s, spatial_tolerance_m. | submit |
| GET | /v1/flashgroups/{id} | A flash group with its members, when its event is visible to you. | read:public |
| POST | /v1/flashgroups/{id}/versions | New version of a flash group (owner or reviewer); group_status changes need review. | submit |
| POST | /v1/flashgroups/{id}/members | Propose your clip as a member: media_asset_id, viewpoint_note, estimated_offset_ms, sync_uncertainty_ms. Confirmation is a reviewer's act. | submit |
| POST | /v1/flashgroupmembers/{mid}/versions | New version of a membership: membership_status (proposed, confirmed by review, disputed with membership_evidence, removed). | submit |
Circles
A circle is a list of people the owner names so that circle-visibility records can be shared with them. It is a list, not a social network.
| Method | Address | What it does | Scope |
|---|---|---|---|
| POST | /v1/circles | Create a circle: circle_name. | submit |
| GET | /v1/circles/{id} | A circle and its active members (owner or member). | submit |
| POST | /v1/circles/{id}/versions | New version of a circle: circle_name, circle_status. | submit |
| POST | /v1/circles/{id}/members | Add a member (owner only): member_actor_id. | submit |
| POST | /v1/circlemembers/{mid}/versions | Leave or remove: membership_status removed (the member or the owner). Only the owner can re-add. | submit |
Change feed
Every new row, in order, so a client can keep a copy current.
| Method | Address | What it does | Scope |
|---|---|---|---|
| GET | /v1/changes | The change feed: row-ordered additions across record kinds. cursor is the last row_id you saw. | read:public |
Search
One query across events, entities, sources and claims, with the same visibility rules as every other read.
| Method | Address | What it does | Scope |
|---|---|---|---|
| GET | /v1/search | Search events, entities, sources and claims at once: q (required), kinds (comma list, default all four), limit. Matches whole words and word beginnings: every word of 3 or more letters in q must appear, and very common words such as "the" are ignored; a q with no such word falls back to matching the text anywhere. Entity aliases always match anywhere. Most recently changed matches first, only those visible to you; meta.truncated says whether there were more. For further pages use that kind's list address with the same q (lists match the text anywhere). | read:public |
Key requests
How an outside developer gets a key. The request is appended, a person decides, and on approval the key is shown once in the decision response and delivered by the approver. Only a fingerprint is stored.
| Method | Address | What it does | Scope |
|---|---|---|---|
| POST | /v1/keyrequests | Ask for a key, no key needed: requester_name, requester_email, organization, application_name, intended_use (20 to 2000 characters), requested_scopes (submit only). Limits: 3 pending per email, 5 per address per day. | read:public |
| GET | /v1/keyrequests | The review queue by status (pending, approved, denied, withdrawn). Scope admin. | admin |
| GET | /v1/keyrequests/{id} | Status of a request by its id, for the requester. Shows the decision note, never the key. | read:public |
| POST | /v1/keyrequests/{id}/decisions | Decide: decision (approve, deny), decision_note (required to deny), granted_scopes (submit, review), trust_tier, expires_at, expected_version. On approve the response carries the key once. Scope admin. | admin |
| POST | /v1/keyrequests/{id}/withdrawals | Withdraw your own pending request: withdraw_secret (returned once when you submitted), reason. No key needed. | read:public |
Your keys
See, rotate and revoke the keys you own without asking anyone. A key value is never shown again after the response that created it, and only its fingerprint is stored.
| Method | Address | What it does | Scope |
|---|---|---|---|
| GET | /v1/keys | Your keys (keys of applications you own, or issued on your behalf): id, scopes, state (active, expired, revoked), expiry, and which one you are calling with. status: active (default), expired, revoked, all. Never shows a key value or fingerprint. | key |
| POST | /v1/keys/{id}/rotations | Replace one of your active keys with a new one carrying the same scopes and expiry; the new key is in this response only. overlap_hours (0 to 72, default 0) keeps the old key working that long so you can switch over; 0 revokes it at once. reason optional. | key |
| POST | /v1/keys/{id}/revocations | Revoke one of your keys now: reason (3 to 480 characters). A key may revoke itself. The last working admin key cannot be revoked. | key |
Tightening
A time position may borrow its limits from another (a photo taken sometime during a person's life borrows the life's limits). When the record it borrows from gets tighter limits, the borrower is flagged. A person with the review scope approves or dismisses each flag; the server never tightens a record on its own.
| Method | Address | What it does | Scope |
|---|---|---|---|
| GET | /v1/time/tightenings | The flag list: borrowed time positions whose container changed. flag_status (open, approved, dismissed; default open), limit, cursor. Each flag shows the borrower's current limits, the container's current limits and the limits the borrower would get if approved. Scope review. | review |
| POST | /v1/time/tightenings/{fid}/decisions | Decide a flag: decision approve or dismiss, note. Approval writes the borrower's new version with limits recomputed from the container as it is now (its written value and duration still narrow them); dismissal leaves the borrower as it is. You cannot approve a tightening of your own record. Scope review. | review |
Places
A place is a shape that changes over time. Each shape of a place record (an entity of type place) carries the dates it was true, the place it sat inside at that time, and where the shape came from. St. Louis in 1903 and St. Louis today are two shapes of one place. Today's borders go in first; older shapes are added as further dated shapes. The present-day boundaries of 231 countries and territories are loaded as public place records from geoBoundaries (gbOpen, administrative level 0, Creative Commons Attribution 4.0; www.geoboundaries.org), each with its source and the year it represents in the shape's note. A point is a small circle: every circle has a radius and every coordinate an error distance, never zero.
| Method | Address | What it does | Scope |
|---|---|---|---|
| POST | /v1/entities/{id}/shapes | Add a shape to your place: shape_kind circle (center_latitude, center_longitude, radius_m more than zero) or polygon / multipolygon (geometry_wkt in well-known text, longitude then latitude, rings closed); valid_written says when the shape was true in the Extended Date/Time Format (1903, 1876-08-01/.., ../1899; omit for always); within_entity_id names the place it sat inside; shape_role (boundary, footprint, approximate, other), boundary_source, source_id, note. The server works out the bounding box, point count and the validity limits. spatial_frame_id defaults to Earth WGS 84. | submit |
| GET | /v1/entities/{id}/shapes | The shapes of a place visible to you, without their outlines: each entry says how large the outline is (geometry_bytes) and links to it (links.geometry). at (a written date) keeps only the shapes true at that time; shape_status (active, retracted; default active); limit, cursor. | read:public |
| POST | /v1/shapes/{shid}/versions | New version of a shape (owner of the place, or a reviewer): any shape field, valid_written, within_entity_id, shape_status retracted; change_reason required. | submit |
| GET | /v1/shapes | Which places contain a point: lat, lon (decimal degrees), optional at (a written date). Candidates come from the bounding box; each is then tested exactly (distance for circles, ray casting for polygons with holes). Answers name the shapes and their places without the outlines (a country outline can be a megabyte); follow links.geometry when you need one. | read:public |
| GET | /v1/shapes/{shid} | One shape with its full outline (geometry_wkt, well-known text, longitude then latitude), following the visibility of its place. | read:public |
Universal positions
Every observed position can be restated on one universal standard: the International Celestial Reference Frame (directions pinned to 303 distant quasars) measured from the solar system's centre of mass, as a state vector in kilometres and kilometres per second. Chronum asks NASA's Horizons service behind its own server after the caller's answer is sent, retries when the service is busy, and stores each answer with the service, its data version and when it was asked. The observed position is never changed; a later improvement by NASA becomes a new version and the old one stays. A body-centre vector stands for a spot on that body with an uncertainty of at least the body's radius; a spacecraft is itself.
| Method | Address | What it does | Scope |
|---|---|---|---|
| POST | /v1/place/{sid}/universal | Ask for the universal position of an observed place position (owner of its record, or a reviewer). at_written: the instant, Extended Date/Time Format in Universal Time (default: the start of the record's first time position); horizons_target: a Horizons body or spacecraft number (default: taken from the position's body — Earth 399, Mars 499, Moon 301, Sun 10 and the planets); uncertainty_km (raised to the body radius plus the position's own uncertainty when a body centre is used); note. Answers 202 with the queued row; the lookup runs after this answer and retries up to six times. | submit |
| GET | /v1/place/{sid}/universal | The universal positions asked for on an observed position: lookup_status (queued, done, failed), the state vector x_km y_km z_km and vx_km_s vy_km_s vz_km_s on the International Celestial Reference Frame from the solar system barycentre, jd_ut, target_name, ephemeris_source, provider_version, fetched_at, last_error. Reading nudges stale lookups along; readers never wait on NASA. limit, cursor. | read:public |
Documentation
This page and its machine-readable form.
| Method | Address | What it does | Scope |
|---|---|---|---|
| GET | /v1/docs | This page. | read:public |
| GET | /v1/docs/openapi | An OpenAPI 3.0 description of every address, with response schemas derived from the frozen response shapes. | read:public |
Response shapes
Frozen for interface version 2026-10-29 on 2026-11-01. Key names and value types; an automated suite compares the live server with these on every deploy.
GET /v1/health health
{
data: {
api_version: string
build: string
database: string
insert_only: bool
region_policy: {
blocked_regions: int
dataset: string
dataset_built: string
lookup_source: string
}
schema_migration: int
status: string
}
meta: {
api_version: string
build: string
request_id: string
server_time: string
}
ok: bool
}GET /v1/timeframes timeframes_list
{
data: {
time_frames: list of {
algorithm_version: string
base_unit: string
body: string
conversion_algorithm: string
epoch_description: string
frame_code: string
leap_second_treatment: string
recorded_at: string
time_frame_id: string
validity_notes: string
version_no: int
}
}
meta: {
api_version: string
build: string
count: int
request_id: string
server_time: string
}
ok: bool
}GET /v1/spatialframes spatialframes_list
{
data: {
spatial_frames: list of {
axes_description: string
body: string
datum_or_origin: string
epoch_description: string
frame_code: string
recorded_at: string
spatial_frame_id: string
transform_notes: string
units: string
version_no: int
}
}
meta: {
api_version: string
build: string
count: int
request_id: string
server_time: string
}
ok: bool
}GET /v1/events events_list
{
data: {
events: list of anything
}
meta: {
api_version: string
build: string
count: int
limit: int
next_cursor: null
request_id: string
server_time: string
}
ok: bool
}GET /v1/events/{id} event_get
{
data: {
event: {
change_reason: string
event_id: string
event_status: string
links: {
claims: string
versions: string
}
owner_actor_id: string
recorded_at: string
recorded_by_actor_id: string
recorded_via_application_id: string
retraction_reason: null
spatial_positions: list of {
altitude_m: null
body: string
coord_x: null
coord_y: null
coord_z: null
coordinate_kind: string
geometry_kind: string
geometry_wkt: null
inside_entity_id: null
latitude: string
longitude: string
observation_time_note: null
place_label: string
position_role: string
source_id: null
spatial_frame_id: string
spatial_position_id: string
uncertainty_m: string
version_no: int
}
summary: null
supersedes_row_id: int
temporal_positions: list of {
algorithm_version: string
begin_earliest_s: string
begin_latest_s: string
calendar: null
certainty: string
conversion_algorithm: string
conversion_note: string
duration_s: null
earliest_s: string
end_earliest_s: string
end_latest_s: string
inside_temporal_position_id: null
latest_s: string
original_value: string
position_role: string
precision_code: string
source_id: string
source_mark: null
temporal_position_id: string
time_frame_id: string
time_scale: null
version_no: int
written: string
}
title: string
version_no: int
version_row_id: int
visibility: string
}
}
meta: {
api_version: string
build: string
request_id: string
server_time: string
}
ok: bool
}GET /v1/events/{id}/versions event_versions
{
data: {
event_id: string
versions: list of {
change_reason: string
event_id: string
event_status: string
owner_actor_id: string
recorded_at: string
recorded_by_actor_id: string
recorded_via_application_id: string
retraction_reason: null
summary: null
supersedes_row_id: int
title: string
version_no: int
version_row_id: int
visibility: string
}
}
meta: {
api_version: string
build: string
count: int
request_id: string
server_time: string
}
ok: bool
}GET /v1/events/{id}/claims event_claims
{
data: {
claims: list of {
claim_id: string
claim_status: string
links: {
claim: string
}
object_value: string
predicate: string
qualifiers: {
pilot: string
}
recorded_at: string
retraction_reason: null
subject_id: string
subject_kind: string
version_no: int
visibility: string
}
event_id: string
}
meta: {
api_version: string
build: string
count: int
request_id: string
server_time: string
}
ok: bool
}GET /v1/claims/{id} claim_get
{
data: {
claim: {
change_reason: string
claim_id: string
claim_status: string
event_id: string
evidence: list of {
canonical_uri: string
evidence_link_id: string
excerpt: string
link_status: string
locator: string
relation: string
source_id: string
source_title: string
source_type: string
version_no: int
}
object_value: string
owner_actor_id: string
predicate: string
qualifiers: {
pilot: string
}
recorded_at: string
recorded_by_actor_id: string
retraction_reason: null
reviews: list of {
decision: string
notes: string
policy_version: string
recorded_at: string
review_id: string
reviewer_actor_id: string
}
subject_id: string
subject_kind: string
version_no: int
visibility: string
}
}
meta: {
api_version: string
build: string
request_id: string
server_time: string
}
ok: bool
}GET /v1/sources/{id} source_get
{
data: {
source: {
archival_locator: null
canonical_uri: string
change_reason: string
cited_by: list of {
claim_id: string
link_status: string
locator: string
relation: string
}
creator: null
owner_actor_id: string
publisher: string
recorded_at: string
rights_note: null
source_date_note: null
source_id: string
source_type: string
title: string
version_no: int
visibility: string
}
}
meta: {
api_version: string
build: string
request_id: string
server_time: string
}
ok: bool
}GET /v1/entities/{id} entity_get
{
data: {
entity: {
aliases: list of string
canonical_label: string
change_reason: string
circle_id: null
description: string
entity_id: string
entity_status: string
entity_type: string
external_ids: {
wikidata: string
}
is_living_private_person: bool
merged_into_entity_id: null
owner_actor_id: string
recorded_at: string
recorded_by_actor_id: string
relationships: list of {
from_id: string
from_kind: string
relation_code: string
relationship_id: string
relationship_status: string
source_id: null
time_bounds_note: null
to_id: string
to_kind: string
version_no: int
}
row_id: int
supersedes_row_id: int
version_no: int
visibility: string
}
}
meta: {
api_version: string
build: string
request_id: string
server_time: string
}
ok: bool
}GET /v1/carettags/{key} carettag_get
{
data: {
caret_tag: {
caret_tag_id: string
change_reason: string
literal_tag: string
merged_into_caret_tag_id: null
namespace_note: null
normalized_key: string
recorded_at: string
recorded_by_actor_id: string
row_id: int
subjects: list of anything
supersedes_row_id: null
tag_status: string
version_no: int
}
}
meta: {
api_version: string
build: string
count: int
request_id: string
server_time: string
}
ok: bool
}GET /v1/flashgroups/{id} flashgroup_get
{
data: {
flash_group: {
change_reason: string
event_id: string
flash_group_id: string
group_status: string
grouping_rule_note: string
links: {
event: string
}
members: list of anything
owner_actor_id: string
recorded_at: string
recorded_by_actor_id: string
row_id: int
spatial_tolerance_m: string
supersedes_row_id: null
temporal_tolerance_s: string
version_no: int
}
}
meta: {
api_version: string
build: string
count: int
request_id: string
server_time: string
}
ok: bool
}GET /v1/circles/{id} circle_get
{
data: {
circle: {
change_reason: string
circle_id: string
circle_name: string
circle_status: string
members: list of anything
owner_actor_id: string
recorded_at: string
recorded_by_actor_id: string
row_id: int
supersedes_row_id: null
version_no: int
}
}
meta: {
api_version: string
build: string
count: int
request_id: string
server_time: string
}
ok: bool
}GET /v1/changes changes
{
data: {
changes: list of {
event_status: string
id: string
kind: string
recorded_at: string
row_id: int
version_no: int
}
}
meta: {
api_version: string
build: string
count: int
next_cursor: int
note: string
request_id: string
server_time: string
}
ok: bool
}GET /v1/media/{id} media_get
{
data: {
media_asset: {
asset_status: string
authenticity_class: string
byte_size: int
capture_metadata: null
change_reason: string
circle_id: null
derived_from_media_asset_id: null
event_id: string
hash_verified: int
media_asset_id: string
media_type: string
mime_type: string
original_filename: string
owner_actor_id: string
recorded_at: string
recorded_by_actor_id: string
retraction_reason: null
rights_note: null
row_id: int
sha256: null
storage_etag: null
supersedes_row_id: null
transformation_note: null
uploader_consent_note: null
version_no: int
visibility: string
}
}
meta: {
api_version: string
build: string
note: string
request_id: string
server_time: string
}
ok: bool
}GET /v1/keyrequests/{id} keyrequest_public_get
{
data: {
key_request: {
application_name: string
decided_at: string
decision_note: string
granted_scopes: list of string
key_request_id: string
links: {
self: string
}
organization: string
request_status: string
requested_at: string
requested_scopes: list of string
requester_name: string
version_no: int
}
}
meta: {
api_version: string
build: string
request_id: string
server_time: string
}
ok: bool
}GET /v1/keyrequests keyrequest_admin_queue
{
data: {
key_requests: list of {
application_name: string
decided_at: string
decided_by_actor_id: string
decision_note: string
granted_scopes: null
intended_use: string
key_request_id: string
links: {
self: string
}
organization: string
request_status: string
requested_at: string
requested_scopes: list of string
requester_email: string
requester_name: string
resulting_actor_id: null
resulting_api_key_id: null
resulting_application_id: null
version_no: int
}
}
meta: {
api_version: string
build: string
count: int
limit: int
next_cursor: int
request_id: string
server_time: string
status: string
}
ok: bool
}GET /v1/entities entities_list
{
data: {
entities: list of {
aliases: list of string
canonical_label: string
entity_id: string
entity_status: string
entity_type: string
is_living_private_person: bool
links: {
self: string
}
recorded_at: string
version_no: int
visibility: string
}
}
meta: {
api_version: string
build: string
count: int
limit: int
next_cursor: null
request_id: string
server_time: string
}
ok: bool
}GET /v1/sources sources_list
{
data: {
sources: list of {
canonical_uri: null
creator: null
links: {
self: string
}
publisher: null
recorded_at: string
source_id: string
source_type: string
title: string
version_no: int
visibility: string
}
}
meta: {
api_version: string
build: string
count: int
limit: int
next_cursor: null
request_id: string
server_time: string
}
ok: bool
}GET /v1/claims claims_list
{
data: {
claims: list of {
claim_id: string
claim_status: string
event_id: string
links: {
self: string
}
object_value: string
predicate: string
qualifiers: null
recorded_at: string
subject_id: string
subject_kind: string
version_no: int
visibility: string
}
}
meta: {
api_version: string
build: string
count: int
limit: int
next_cursor: null
request_id: string
server_time: string
}
ok: bool
}GET /v1/search search
{
data: {
results: list of {
id: string
kind: string
label: string
links: {
self: string
}
recorded_at: string
status: string
visibility: string
}
}
meta: {
api_version: string
build: string
count: int
kinds: list of string
limit: int
request_id: string
server_time: string
truncated: bool
}
ok: bool
}GET /v1/keys keys_list
{
data: {
keys: list of {
api_key_id: string
application_id: string
application_name: string
created_at: string
expires_at: null
is_this_key: bool
key_prefix: string
key_status: string
last_changed_at: string
links: {
revocations: string
rotations: string
}
on_behalf_of_actor_id: string
permission_scopes: list of string
state: string
version_no: int
}
}
meta: {
api_version: string
build: string
count: int
limit: int
next_cursor: int
request_id: string
server_time: string
status: string
}
ok: bool
}GET /v1/media media_list
{
data: {
media: list of {
asset_status: string
authenticity_class: string
byte_size: int
event_id: string
links: {
self: string
}
media_asset_id: string
media_type: string
mime_type: string
original_filename: string
recorded_at: string
version_no: int
visibility: string
}
}
meta: {
api_version: string
build: string
count: int
limit: int
next_cursor: null
request_id: string
server_time: string
}
ok: bool
}GET /v1/relationships relationships_list
{
data: {
relationships: list of {
from_id: string
from_kind: string
links: {
from: string
to: string
}
recorded_at: string
relation_code: string
relationship_id: string
relationship_status: string
source_id: null
time_bounds_note: null
to_id: string
to_kind: string
version_no: int
}
}
meta: {
api_version: string
build: string
count: int
limit: int
next_cursor: null
request_id: string
server_time: string
}
ok: bool
}GET /v1/carettags carettags_list
{
data: {
caret_tags: list of {
caret_tag_id: string
links: {
self: string
}
literal_tag: string
namespace_note: null
normalized_key: string
recorded_at: string
tag_status: string
version_no: int
}
}
meta: {
api_version: string
build: string
count: int
limit: int
next_cursor: null
request_id: string
server_time: string
}
ok: bool
}GET /v1/time/tightenings tightenings_list
{
data: {
tightenings: list of {
borrower: {
current_limits: {
begin_earliest_s: string
begin_latest_s: string
end_earliest_s: string
end_latest_s: string
}
duration_s: string
subject_id: string
subject_kind: string
temporal_position_id: string
version_no: int
written: null
}
container: {
changed_in_row_id: int
current_limits: {
begin_earliest_s: string
begin_latest_s: string
end_earliest_s: string
end_latest_s: string
}
temporal_position_id: string
version_no: int
}
decided_at: null
decided_by_actor_id: null
decision_note: null
flag_status: string
flagged_at: string
links: {
borrower_versions: string
decisions: string
self: string
}
proposal_error: null
proposed_limits: {
begin_earliest_s: string
begin_latest_s: string
end_earliest_s: string
end_latest_s: string
}
resulting_version_no: null
time_tightening_flag_id: string
version_no: int
}
}
meta: {
api_version: string
build: string
count: int
flag_status: string
limit: int
next_cursor: null
request_id: string
server_time: string
}
ok: bool
}GET /v1/entities/{id}/shapes shapes_list
{
data: {
shapes: list of {
bbox_max_lat: string
bbox_max_lon: string
bbox_min_lat: string
bbox_min_lon: string
boundary_source: string
center_latitude: null
center_longitude: null
change_reason: string
entity_id: string
geometry_bytes: int
links: {
geometry: string
place: string
self: string
versions: string
within: string
}
note: null
place_shape_id: string
point_count: int
radius_m: null
recorded_at: string
recorded_by_actor_id: string
row_id: int
shape_kind: string
shape_role: string
shape_status: string
source_id: null
spatial_frame_id: string
supersedes_row_id: null
valid_from_s: string
valid_to_s: null
valid_written: string
version_no: int
within_entity_id: string
}
}
meta: {
api_version: string
at: null
build: string
count: int
limit: int
next_cursor: null
request_id: string
server_time: string
}
ok: bool
}GET /v1/shapes shapes_containing
{
data: {
shapes: list of {
bbox_max_lat: string
bbox_max_lon: string
bbox_min_lat: string
bbox_min_lon: string
boundary_source: string
center_latitude: null
center_longitude: null
change_reason: string
entity_id: string
geometry_bytes: int
links: {
geometry: string
place: string
self: string
versions: string
within: string
}
note: null
place_shape_id: string
point_count: int
radius_m: null
recorded_at: string
recorded_by_actor_id: string
row_id: int
shape_kind: string
shape_role: string
shape_status: string
source_id: null
spatial_frame_id: string
supersedes_row_id: null
valid_from_s: string
valid_to_s: null
valid_written: string
version_no: int
within_entity_id: string
}
}
meta: {
api_version: string
at: null
build: string
count: int
limit: int
next_cursor: null
note: string
request_id: string
server_time: string
}
ok: bool
}GET /v1/shapes/{shid} shape_get
{
data: {
shape: {
bbox_max_lat: string
bbox_max_lon: string
bbox_min_lat: string
bbox_min_lon: string
boundary_source: string
center_latitude: null
center_longitude: null
change_reason: string
entity_id: string
geometry_bytes: int
geometry_wkt: string
links: {
geometry: string
place: string
self: string
versions: string
within: string
}
note: null
place_shape_id: string
point_count: int
radius_m: null
recorded_at: string
recorded_by_actor_id: string
row_id: int
shape_kind: string
shape_role: string
shape_status: string
source_id: null
spatial_frame_id: string
supersedes_row_id: null
valid_from_s: string
valid_to_s: null
valid_written: string
version_no: int
within_entity_id: string
}
}
meta: {
api_version: string
build: string
request_id: string
server_time: string
}
ok: bool
}GET /v1/place/{sid}/universal universal_list
{
data: {
universal_positions: list of {
at_s: string
at_written: string
attempts: int
center: string
change_reason: string
ephemeris_source: string
fetched_at: string
horizons_target: string
jd_ut: string
last_error: null
links: {
observed: string
self: string
subject: string
}
lookup_status: string
note: null
owner_actor_id: string
provider: string
provider_version: string
recorded_at: string
recorded_by_actor_id: string
reference_frame: string
request_url: string
response_excerpt: string
row_id: int
spatial_position_id: string
subject_id: string
subject_kind: string
supersedes_row_id: int
target_name: string
uncertainty_km: string
universal_position_id: string
version_no: int
vx_km_s: string
vy_km_s: string
vz_km_s: string
x_km: string
y_km: string
z_km: string
}
}
meta: {
api_version: string
build: string
count: int
limit: int
next_cursor: null
request_id: string
server_time: string
standard: string
}
ok: bool
}Error envelope error_404
{
error: {
code: string
message: string
type: string
}
meta: {
api_version: string
build: string
request_id: string
server_time: string
}
ok: bool
}Region error envelope error_451
{
error: {
code: string
message: string
policy: string
region: string
type: string
}
meta: {
api_version: string
build: string
request_id: string
server_time: string
}
ok: bool
}Errors
| Status | Type | Codes | Meaning |
|---|---|---|---|
400 | invalid_request_error | invalid_json, missing_field, invalid_field, unknown_field, reason_required, change_reason_required, decision_note_required, retraction_reason_required, evidence_required, false_precision, invalid_range | The request is malformed or breaks a rule. The message says which field. |
401 | authentication_error | invalid_key, key_revoked, key_expired, application_disabled, missing_scope (anonymous) | No usable key. |
403 | permission_error | missing_scope, not_owner, review_required, self_review, wrong_secret, withdraw_not_available | The key is valid but may not do this. |
404 | invalid_request_error | not_found, reference_not_found | No such address or record, or not visible to you. |
405 | invalid_request_error | method_not_allowed | Wrong method; the Allow header lists the right ones. |
409 | conflict_error | stale_version, version_exists, already_assigned, already_decided, not_uploaded, already_revoked, key_revoked, key_expired, last_admin_key | Changed since you read it, or already done. |
410 | invalid_request_error | gone | A file-name style address, or a media asset that is unpublished or retracted (with the reason). |
429 | rate_limit_error | too_many_pending, too_many_requests | Slow down. |
451 | region_error | region_not_served | The service is not offered in your region. |
500 / 503 | api_error | internal, query_failed, insert_failed, not_configured, db_unavailable, storage_not_configured, queue_full | Our side. Quote meta.request_id. |
Country data: IP Geolocation by DB-IP, Creative Commons Attribution 4.0. Chronum never updates or deletes a row; every version of every record is kept. Request id for this page: 01M6E20J2MQBN2B95RHN86FD48.