Schemas

The data formats Sato Hub publishes

Every machine-readable shape Sato Hub emits, written as JSON Schema (draft 2020-12) at a stable URL. Point a validator at one and check our output, or your own — the formats are yours to implement.

A schema validates structure and nothing else. Nothing here blesses anything: a Sato Score measures how open, active and verifiable a project is, a verified install records that a documented install was reproduced in a container on a date, and a null means unknown rather than zero.

Stability

v1 is additive-only: new optional properties may appear, but an existing property never changes meaning, type or nullability and is never removed. A breaking change is published as v2 at a new URL and v1 keeps serving. Validate with additional properties allowed.

Validate with additional properties allowed. A consumer pinned to v1 must not start failing the day a field is added, which is why every response schema is open and only the sato.deploy manifest — a document other people author, where an unknown key is more likely a typo than a feature — is closed.

Check one

curl -s https://satohub.ai/schemas/export-listing/v1.json -o export-listing.json
curl -s https://satohub.ai/api/export/index.json | jq '.resources[0]' > sample.json
npx ajv-cli validate -s export-listing.json -d sample.json --spec=draft2020

The whole catalogue in one request: https://satohub.ai/schemas/index.json.

The formats

Export listing

One catalog listing as the free export publishes it — identity, links, chains, standards, score, liveness and deploy manifest. Catalog facts only: no score history, no provenance, no commercial fields, and a score is never a safety or quality judgment.

Schema: https://satohub.ai/schemas/export-listing/v1.json
Sample: /api/export/index.json
Announced by: a $schema property in the body

Change feed

The delta a mirror polls instead of re-downloading the catalog: added, updated, changed and removed, with the baseline date to store as a cursor. It is a notification feed, not a guaranteed-complete replication log, and every response says which lanes are approximate.

Schema: https://satohub.ai/schemas/change-feed/v1.json
Sample: /api/changes?since=2026-09-01
Announced by: a $schema property in the body

sato.deploy manifest

The minimal manifest for standing a resource up: runtime, install, entry, requirements, and whether the documented install was reproduced in a container. deploy_status records deployability on a date; it is never a safety, quality or audit claim.

Schema: https://satohub.ai/schemas/deploy-spec.json
Sample: /api/export/index.json
Announced by: the document's own top-level version field

Agent Passport manifest

The machine-readable passport for one registered agent: identity, declared stack, links, payment metadata and on-chain checks. Registration is self-declared, and a verified wallet proves control of a key rather than anything about the product behind it.

Schema: https://satohub.ai/schemas/agent-manifest/v1.json
Sample: /api/agents/{slug}/manifest
Announced by: a $schema property in the body

Preflight verdict

The one call before an agent installs, connects to or pays something: a verdict, the rule that decided it, and every evidence line it rests on. A verdict is a reading of public evidence — go is not a clearance, and unknown is a real answer that is never rounded.

Schema: https://satohub.ai/schemas/preflight-verdict/v1.json
Sample: /api/preflight?package=solana-agent-kit
Announced by: a Link: <url>; rel="describedby" response header — the body is signed, so a property would change bytes a verifier was told to hash

Sato Route receipt

The record of one quoted route and, when a caller reports it back, the transaction that carried it. It is an observation, not revenue: the fee is a parameter we sent, amounts are base-unit strings, and receipts must not be summed and called income.

Schema: https://satohub.ai/schemas/route-receipt/v1.json
Sample: /api/route/receipt
Announced by: a Link: <url>; rel="describedby" response header — the body is signed, so a property would change bytes a verifier was told to hash

Signed response envelope

The envelope shared by every signed Sato Hub response: the payload plus meta.signature, with the header signature covering the exact bytes. A null signature means the deployment had no key — unsigned is published as unsigned, never as a placeholder.

Schema: https://satohub.ai/schemas/signed-envelope/v1.json
Sample: /api/export/score-inputs.json
Announced by: a Link: <url>; rel="describedby" response header — the body is signed, so a property would change bytes a verifier was told to hash

Build plan

A grounded stack for a stated goal: components with their scores, deploy manifests and Preflight verdicts, matching skills with their disclosures, the gaps, and one first action. A recommendation read off public evidence — the gaps are part of the answer, not a failure of it.

Schema: https://satohub.ai/schemas/build-plan/v1.json
Sample: /api/satobot/plan
Announced by: a Link: <url>; rel="describedby" response header — the body is signed, so a property would change bytes a verifier was told to hash

Skill disclosure

One agent skill with a static disclosure of what its own text declares: hosts contacted, key generation, credential requests, tool grants. A disclosure describes and never clears; an empty flag list means nothing matched, and a registry's scan belongs to that registry.

Schema: https://satohub.ai/schemas/skill-disclosure/v1.json
Sample: /api/export/skills.json
Announced by: a $schema property in the body

Sato Score inputs

Every input the Sato Score is computed from, with the instant the published scores were computed against, so anyone can run the rubric and check our arithmetic. Score it at a later instant and the number legitimately differs — as_of is what makes a reproduction comparable.

Schema: https://satohub.ai/schemas/score-inputs/v1.json
Sample: /api/export/score-inputs.json
Announced by: a Link: <url>; rel="describedby" response header — the body is signed, so a property would change bytes a verifier was told to hash

Sato Score roots

One Merkle root per UTC day over the scores published that day, with the exact leaf and node construction and an optional on-chain anchor. A root proves what was published and when; it proves nothing about whether a score is right.

Schema: https://satohub.ai/schemas/score-roots/v1.json
Sample: /.well-known/sato-score-roots.json
Announced by: the document's own top-level version field

Reusing them

These formats are published so other tools can adopt them, not only so ours can be checked. Copy them, implement them, disagree with them in public. If a schema and the live response disagree, that is our bug — the transparency report is where corrections land.