Docs index

World API

Reading a compiled World, its objects, relations and evidence.

Reading a World by collection id

A World is read by collection id. Objects carry their stable keys, the relations they participate in and the evidence they rest on; evidence carries the source version, the page and the region.

Finding a World to read

An agent holding only an API key needs a way to find out which collection ids exist without a person pasting one in. Only active Worlds are listed: a candidate nobody activated is not what the workspace answers from, and a list mixing the two would present unaccepted output as organizational truth.

GET/collectionsScope collections:read

The calling workspace's active Compiled Worlds, keyset-paginated on collection id. `page.nextCursor` is the last collection id on this page, or null on the last page. The workspace comes from the credential; there is no workspace parameter.

curl -sS -X GET https://tavonel.com/api/v1/collections \
  -H "Authorization: Bearer $TAVONEL_API_KEY"

import os
import requests

response = requests.request(
    "GET",
    "https://tavonel.com/api/v1/collections",
    headers={"Authorization": "Bearer " + os.environ["TAVONEL_API_KEY"]},
    timeout=30,
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://tavonel.com/api/v1/collections", {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.TAVONEL_API_KEY}` },
});
if (!response.ok) throw new Error(`${response.status} ${(await response.json()).code}`);
console.log(await response.json());

Status	Response
`200`	One page of active Worlds.
`400`	WORLD_PAGE_LIMIT_INVALID — `limit` was outside 1–50. WORLD_PAGE_CURSOR_INVALID — The cursor named an id this lens does not contain. A wrong cursor is refused rather than answered with an empty page, so a paging bug is visible instead of silent.
`401`	AUTH_REQUIRED — No credential was presented, or the bearer token is not a key TAVONEL issued. This is what an unauthenticated request to any scoped route returns.
`403`	API_SCOPE_REQUIRED — The key authenticated and does not carry the scope this operation requires. The request was refused rather than answered with less. PILOT_ACCESS_REQUIRED — The credential is valid and the workspace it names is not admitted to TAVONEL.
`503`	WORLD_STORE_READ_FAILED — The World store could not be read. WORLD_STORE_NOT_CONFIGURED — The World store is not configured.

GET/collections/{id}/worldScope worlds:read

Which version this collection currently answers from, and which prior versions are retained. Use GET /world/{id} for the read model itself and GET /world/{id}/{lens} for one lens of it.

curl -sS -X GET https://tavonel.com/api/v1/collections/{id}/world \
  -H "Authorization: Bearer $TAVONEL_API_KEY"

import os
import requests

response = requests.request(
    "GET",
    "https://tavonel.com/api/v1/collections/{id}/world",
    headers={"Authorization": "Bearer " + os.environ["TAVONEL_API_KEY"]},
    timeout=30,
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://tavonel.com/api/v1/collections/{id}/world", {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.TAVONEL_API_KEY}` },
});
if (!response.ok) throw new Error(`${response.status} ${(await response.json()).code}`);
console.log(await response.json());

Status	Response
`200`	The active pointer and the retained versions.
`400`	COLLECTION_ID_INVALID — The collection id did not match `collection-<32 hex>`.
`401`	AUTH_REQUIRED — No credential was presented, or the bearer token is not a key TAVONEL issued. This is what an unauthenticated request to any scoped route returns.
`404`	NOT_FOUND — The addressed resource does not exist in this workspace. Deliberately uniform across tenants: the same answer for an id that is not yours and an id that is nobody's. WORLD_NOT_FOUND — No World for that collection id in this workspace.
`409`	ACTIVE_WORLD_NOT_FOUND — Nothing has been activated for this collection, so there is no World to read, index or answer from. A candidate nobody accepted is not a smaller answer — it is a different one.
`503`	WORLD_STORE_READ_FAILED — The World store could not be read.

The six lenses

Lens	What it holds	Pages
objects	Every Object, with its stable key and label.	limit and cursor
relations	Every relation, with the objects it joins.	limit and cursor
evidence	Every region, with its source version, page and bbox in the 0-1000 frame.	limit and cursor
history	The version history of this collection.	no — answers WORLD_LENS_NOT_PAGEABLE
files	The sources this World was compiled from.	no — answers WORLD_LENS_NOT_PAGEABLE
review	Recorded human decisions over evidence.	no — answers WORLD_LENS_NOT_PAGEABLE

The whole read model, or one lens

GET/world/{id}Scope worlds:read

The whole World read model: contract, freshness, objects, relations, evidence, directory, ontology, history, files and review state. `manifest` reads a specific version, which is what a two-version diff needs.

curl -sS -X GET https://tavonel.com/api/v1/world/{id} \
  -H "Authorization: Bearer $TAVONEL_API_KEY"

import os
import requests

response = requests.request(
    "GET",
    "https://tavonel.com/api/v1/world/{id}",
    headers={"Authorization": "Bearer " + os.environ["TAVONEL_API_KEY"]},
    timeout=30,
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://tavonel.com/api/v1/world/{id}", {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.TAVONEL_API_KEY}` },
});
if (!response.ok) throw new Error(`${response.status} ${(await response.json()).code}`);
console.log(await response.json());

Status	Response
`200`	{ code: OK, model }.
`400`	WORLD_ID_INVALID — The World id did not match the collection id pattern. MANIFEST_DIGEST_INVALID — The manifest digest did not match `sha256:<64 hex>`.
`401`	AUTH_REQUIRED — No credential was presented, or the bearer token is not a key TAVONEL issued. This is what an unauthenticated request to any scoped route returns.
`404`	WORLD_NOT_FOUND — No World for that collection id in this workspace.
`422`	WORLD_READ_MODEL_INVALID — The read model failed validation, so nothing was served.
`503`	WORLD_STORE_READ_FAILED — The World store could not be read. WORLD_STORE_NOT_CONFIGURED — The World store is not configured.

GET/world/{id}/{lens}Scope worlds:read

One lens of the World read model. `objects`, `relations` and `evidence` accept `limit` and `cursor`; `history`, `files` and `review` do not and answer WORLD_LENS_NOT_PAGEABLE if asked. Omitting `limit` returns the whole lens and `page.limit: null`. The cursor is the last item id from the previous page -- keyset, not an offset -- and a cursor naming an id the lens does not contain is a 400 rather than an empty page.

curl -sS -X GET https://tavonel.com/api/v1/world/{id}/{lens} \
  -H "Authorization: Bearer $TAVONEL_API_KEY"

import os
import requests

response = requests.request(
    "GET",
    "https://tavonel.com/api/v1/world/{id}/{lens}",
    headers={"Authorization": "Bearer " + os.environ["TAVONEL_API_KEY"]},
    timeout=30,
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://tavonel.com/api/v1/world/{id}/{lens}", {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.TAVONEL_API_KEY}` },
});
if (!response.ok) throw new Error(`${response.status} ${(await response.json()).code}`);
console.log(await response.json());

Status	Response
`200`	{ code: OK, world, contract, freshness, <lens>, page }. The lens array is keyed by the lens name, so `objects` comes back under `objects`.
`400`	WORLD_ID_INVALID — The World id did not match the collection id pattern. WORLD_LENS_NOT_PAGEABLE — `history`, `files` and `review` return whole; `limit` and `cursor` are refused on them. WORLD_PAGE_LIMIT_INVALID — `limit` was outside 1–50. WORLD_PAGE_CURSOR_INVALID — The cursor named an id this lens does not contain. A wrong cursor is refused rather than answered with an empty page, so a paging bug is visible instead of silent.
`401`	AUTH_REQUIRED — No credential was presented, or the bearer token is not a key TAVONEL issued. This is what an unauthenticated request to any scoped route returns.
`404`	WORLD_NOT_FOUND — No World for that collection id in this workspace. WORLD_LENS_NOT_FOUND — The lens name is not one of `objects`, `relations`, `evidence`, `history`, `files`, `review`.
`503`	WORLD_STORE_READ_FAILED — The World store could not be read.

The candidate behind a version

The reviewable candidate artifact is a different read from the World read model: it is the raw compile package, before anyone activated it, and it is what a review surface works against. A World read is what answers come from.

GET/collections/{id}Scope collections:read

The reviewable candidate artifact — the raw compile package, before anyone activated it. This is not the World read model: GET /world/{id} is that, and it answers only for a version a person activated.

curl -sS -X GET https://tavonel.com/api/v1/collections/{id} \
  -H "Authorization: Bearer $TAVONEL_API_KEY"

import os
import requests

response = requests.request(
    "GET",
    "https://tavonel.com/api/v1/collections/{id}",
    headers={"Authorization": "Bearer " + os.environ["TAVONEL_API_KEY"]},
    timeout=30,
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://tavonel.com/api/v1/collections/{id}", {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.TAVONEL_API_KEY}` },
});
if (!response.ok) throw new Error(`${response.status} ${(await response.json()).code}`);
console.log(await response.json());

Status	Response
`200`	The candidate artifact and its validation report.
`400`	COLLECTION_ID_INVALID — The collection id did not match `collection-<32 hex>`.
`401`	AUTH_REQUIRED — No credential was presented, or the bearer token is not a key TAVONEL issued. This is what an unauthenticated request to any scoped route returns.
`404`	NOT_FOUND — The addressed resource does not exist in this workspace. Deliberately uniform across tenants: the same answer for an id that is not yours and an id that is nobody's.
`422`	COLLECTION_PACKAGE_INVALID — The package failed its own validation, so it was not served. COLLECTION_SOURCE_BINDING_INVALID — A package entry cites a source version that cannot be resolved.
`503`	READ_FAILED — A backing store could not be read. R2_NOT_CONFIGURED — Object storage is not configured.

Is the copy I hold still current?

A signed package you downloaded verifies offline and cannot be recalled remotely, and a rollback restores a prior revision without undoing anyone's use of an older answer. Neither of those changes here. What this does is let a holder check, live, whether the digest they hold is still the one the workspace answers from — active: false means a different version is active now, not that the copy was withdrawn, and knownToWorkspace: false is a different answer again: no record of ever activating that digest.

GET/world/{id}/manifest-statusScope worlds:read

Whether a manifest digest is the one this workspace currently answers from. `active: false` means a different version is active now; it does not mean the held copy was withdrawn or deleted, and this endpoint deletes nothing. `knownToWorkspace: false` means this workspace has no record of ever activating that digest, which is a different answer from 'it was superseded'.

curl -sS -X GET https://tavonel.com/api/v1/world/{id}/manifest-status \
  -H "Authorization: Bearer $TAVONEL_API_KEY"

import os
import requests

response = requests.request(
    "GET",
    "https://tavonel.com/api/v1/world/{id}/manifest-status",
    headers={"Authorization": "Bearer " + os.environ["TAVONEL_API_KEY"]},
    timeout=30,
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://tavonel.com/api/v1/world/{id}/manifest-status", {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.TAVONEL_API_KEY}` },
});
if (!response.ok) throw new Error(`${response.status} ${(await response.json()).code}`);
console.log(await response.json());

Status	Response
`200`	The status of that digest against the workspace's current state.
`400`	WORLD_ID_INVALID — The World id did not match the collection id pattern. MANIFEST_DIGEST_INVALID — The manifest digest did not match `sha256:<64 hex>`.
`401`	AUTH_REQUIRED — No credential was presented, or the bearer token is not a key TAVONEL issued. This is what an unauthenticated request to any scoped route returns.
`409`	ACTIVE_WORLD_NOT_FOUND — Nothing has been activated for this collection, so there is no World to read, index or answer from. A candidate nobody accepted is not a smaller answer — it is a different one.
`503`	WORLD_STORE_READ_FAILED — The World store could not be read.

What is never in a response

Note Route features, scores, thresholds and the cost matrix are not in any public response. They are internal, and a public DTO that filtered them would be one refactor away from leaking them.

API version 2026-09-02.1 · reviewed 11 September 2026

Something here out of date or wrong? Report an issue with this page.