Docs index

Exports

The signed package: what is in it, and what the signature covers.

What a package contains

A compiled World exports as a package containing the canonical model, the ontology in Turtle and JSON-LD, the graph as CSV, the retrieval chunks, the evidence and a validation report. Every file carries its own sha256 and the manifest digest covers the set.

Path	What it is
AGENTS.md	What a filesystem-capable agent reads first.
graph/nodes.csv	Graph nodes, for a plain graph import.
graph/relationships.csv	Graph edges, with the relation each one carries.
manifest/ai-entrypoint.json	The machine-readable map of the entrypoints and the grounding rules.
manifest/candidate-world.json	The compiled World this archive was written from — objects and relations, canonically ordered.
manifest/export-manifest.json	A digest for every file above. The signature is made over these bytes.
ontology/knowledge.jsonld	JSON-LD semantic projection, for linked-data consumers.
ontology/knowledge.ttl	The same projection in Turtle, for RDF and SPARQL.
provenance/activities.jsonl	Lineage for every compiled artifact in the package.
rag/chunks.jsonl	Retrieval chunks, each bound to the source location it came from.
rag/documents.jsonl	Document-level retrieval records.
README.md	Where a person starts, and which consumption path to take.
signatures/export-manifest.ed25519.json	The detached Ed25519 signature over that manifest.
validation/report.json	The validation status, and any reason the result still requires review.

Signature states a caller can observe

Artifact	Signature state	What happens
Customer download	Signed, or refused	`GET /v1/collections/{id}/download` signs the manifest with Ed25519 or refuses with `EXPORT_SIGNER_NOT_CONFIGURED` (503). There is no third outcome: you never receive an archive still in the candidate state.
Public sample World	Deliberately unsigned	The sample on the Reproducibility page is a fixture, labelled unsigned, and is not an activated customer World. Do not use it to test the signature path.

Downloading it, and fetching the key to check it with

The download signs the manifest at request time or refuses; there is no candidate archive to receive by accident. The trust record is the other half and is deliberately a separate, unauthenticated call.

GET/collections/{id}/downloadScope collections:download

The signed, hash-verifiable ZIP. Signed or refused: there is no third outcome, and you never receive an archive still in the candidate state. Verify it against the fingerprint from GET /export/trust, never against one inside the archive.

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

import os
import requests

response = requests.request(
    "GET",
    "https://tavonel.com/api/v1/collections/{id}/download",
    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}/download", {
  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 signed package. `manifest/export-manifest.json` carries a digest for every file and `signatures/export-manifest.ed25519.json` is the detached Ed25519 signature over those bytes.
`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. INVALID_SIGNATURE — The signature did not verify against the key it names. EVIDENCE_DANGLING — An object cites evidence that is not in the package.
`503`	EXPORT_SIGNER_NOT_CONFIGURED — No signing key is configured, so neither a signed archive nor a fingerprint can be produced. `GET /export/trust` answers this rather than a fingerprint nobody can verify against. SIGNATURE_READ_FAILED — The detached signature could not be read. R2_NOT_CONFIGURED — Object storage is not configured.

GET/export/trust

The Ed25519 public key every signed export is signed with, and its sha256 fingerprint. Fetched here rather than read out of an archive, because an archive that vouches for its own key has proven nothing. A deployment with no signing key configured answers 503 EXPORT_SIGNER_NOT_CONFIGURED rather than a fingerprint nobody can verify against.

curl -sS -X GET https://tavonel.com/api/export/trust

import requests

response = requests.request(
    "GET",
    "https://tavonel.com/api/export/trust",
    timeout=30,
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://tavonel.com/api/export/trust", {
  method: "GET",
  headers: {},
});
if (!response.ok) throw new Error(`${response.status} ${(await response.json()).code}`);
console.log(await response.json());

Status	Response
`200`	The trust record. Verify a downloaded archive against `publicKeySpkiSha256` from here, never against a fingerprint inside the archive.
`503`	EXPORT_SIGNER_NOT_CONFIGURED — No signing key is configured, so neither a signed archive nor a fingerprint can be produced. `GET /export/trust` answers this rather than a fingerprint nobody can verify against. EXPORT_SIGNER_INVALID — The configured signer did not produce a usable key.

Verifying against a fingerprint you fetch separately

Note The signing key lives with an external signer, so a deployment without one cannot hand out an archive at all. GET /api/export/trust publishes the public key and its sha256 fingerprint, and returns EXPORT_SIGNER_NOT_CONFIGURED by the same rule. Verify against the fingerprint from that endpoint, never against the one inside the archive you are checking.

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

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