Project and keys

Everything below happens on two surfaces. The dashboard at app.sch3ma.com is for people. The API at admin.sch3ma.com is for scripts, CI and coding agents, and is frozen from its first release.

A key is shown once, when it is minted. A publishable key ships in your page by design and carries no authority of its own: the rules on each collection decide what it may do. A secret key carries full project authority and must never reach a browser.

Origins

A project's origin list names the sites that may reach it from a browser. Visitors can only sign in from these. Replacing the list is one of four operations that take two calls, because dropping an origin by leaving it out can lock out every visitor.

First collection

A collection is created with one PUT. It answers 201 and needs no confirmation, because there is nothing yet to destroy.

prefix is the short tag on every record id in the collection, so an id reads rev_01J8ZK9V…. Every record also carries five system columns you never declare: id, created_at, updated_at, version and deleted_at.

Field types

Field options

Access rules

Four rules per collection, one per operation. This is the part that makes a publishable key safe in a page: the key says which project, the rules say what any caller may do.

An absent rule denies everyone below project authority. A collection with only create declared, as a waitlist wants, accepts writes from anyone and lets nobody read the list back.

Field visibility

Rules decide who reaches a record. visible decides who reaches a field inside it. A field the caller may not read is absent from the response rather than blanked, so nothing about it is inferable.

Changing a collection

A change over live data takes two calls. The first reports what it would do and commits nothing; the second repeats the body with the token. Adding a field is a one-call-shaped change that still runs the same flow, so no client meets the destructive path for the first time in production.

A tightening validates forward only: stored records that would now fail are grandfathered, and the report counts them. Add ?_strict=true to refuse the change instead. A dropped field keeps a shadow copy for 30 days, so an accidental drop is recoverable. Deleting a collection is DELETE /_schemas/:name, also two calls, and restorable for 30 days with POST /_schemas/:name/_restore.

References

A reference field points at another collection and is resolved server-side. A reference always reads as an object carrying at least id, never a bare string, so a client reading row.author.id keeps working whether or not the reference was expanded.

An expansion adds keys; it never changes a type. A field the caller may not see on the target stays absent on the expanded object too, so an include cannot be used to read around a visibility rule.

Grants

A grant is a named capability you hand to an identity, for the moderator and editor cases that owner: cannot express. Declare the names first on the reserved _grants collection.

mintable_by says which grant lets a holder mint that grant for someone else, so moderation can be delegated without a secret key. Undeclaring a grant revokes it on the next request: authority is never grandfathered.

Writing records

Reading records

Filters ride as one JSON object under _filter, so a customer's field name can never collide with a parameter name. A bare value means equality; an object takes one or more predicates. Every term is ANDed.

_sort takes up to three keys with an optional leading -; id is appended as a tiebreaker so paging never loses a record. A list answers data, has_more and cursor; pass the cursor back as _cursor. There is no offset and no total. For a count, GET /:collection/_count takes _filter and nothing else and answers {"count":842,"exact":true}.

Idempotency

Every write may carry _idempotency_key. A repeat with the same key and the same request replays the stored status and body under Sch3ma-Replay: true, so a double-submitted form writes once. The same key with a different request is 409 idempotency_conflict. The window is 24 hours.

Versions

Every record carries version, an integer that starts at 1 and rises by exactly one on every accepted write, soft delete and restore included. Pass _version on an update and the write is refused if the record moved underneath you.

Delete and restore

An ordinary delete is soft: it sets deleted_at, bumps the version and hides the record everywhere. A secret key can list deleted records with _deleted=true, restore one, or destroy it for good.

A purge runs the on_delete edges: cascade destroys the records that point at it, set_null clears their field, and restrict refuses the purge while any record still points at it. A soft delete never consults those edges.

Identity settings

One document per project, merged with a single PATCH. An absent key is unchanged; an explicit null returns that key to its default.

Export

One call returns a gzipped tar of the whole project: a file per collection as NDJSON, the identity records, the credentials, and a manifest that replays the schema. Once per hour per project.

Above 10 MB or 50,000 records the call answers a job instead. Poll GET /_export/:id until it is ready, then fetch the single-use URL it names. No secret ever appears in an archive.

Usage

The same counters that enforce the quota are the ones you can read, so the numbers never disagree. The response carries this project's meters, the account's totals, the allowance and the current rung.

Errors

A response carrying data succeeded. Every failure is {"error":{"code":…,"message":…}} with a stable machine code. Branch on the code, never the message.

Reads never answer 401. A list under a rule you do not satisfy is an empty array, and a collection you may not read is the same 404 a misspelling gets, so no response is a probe for what exists.