Records API

CRUD operations for records of any schema.

List records

GET /api/v1/projects/{project}/schemas/{schema}/records

Supports query parameters:

Param	Example	Effect
`page`	`?page=2`	1-indexed page
`pageSize`	`?pageSize=50`	items per page (max 100)
`sort`	`?sort=data.hp` or `?sort=-data.hp`	sort ascending/descending
`filter[KEY]`	`?filter[data.rarity]=rare`	exact match
`filter[KEY][op]`	`?filter[data.hp][gte]=50`	comparison (`eq`, `neq`, `lt`, `lte`, `gt`, `gte`, `in`, `contains`)
`expand`	`?expand=author,tags`	inline referenced records
`package`	`?package=level-1`	filter to one package

Get one record

GET /api/v1/projects/{project}/schemas/{schema}/records/{id}

Create a record

POST /api/v1/projects/{project}/schemas/{schema}/records
Content-Type: application/json

{
  "package": "level-1",
  "data": {
    "name": "Goblin",
    "hp": 20,
    "attack": 3,
    "rarity": "common"
  }
}

If package is omitted, the record is placed in the project's default package.

Returns the created record with its assigned id, created_at, and updated_at.

Send an Idempotency-Key header to make a create safe to retry. If a network blip leaves you unsure whether a POST succeeded, replay the exact same request with the same key and you'll get the original record back instead of creating a duplicate (and burning a record against your plan limit).

POST /api/v1/projects/{project}/schemas/{schema}/records
Content-Type: application/json
Idempotency-Key: 8f1c2e9a-3b7d-4c5e-9a01-2f6d8e3b1c40

{ "package": "level-1", "data": { "name": "Goblin", "hp": 20 } }

The key is any unique string of 1–255 characters. A UUID per logical operation works well.
A replay returns the stored response with an Idempotent-Replayed: true header. The first request returns Idempotent-Replayed: false.
Keys are remembered for 24 hours, scoped to the project and schema.
Reusing a key with a different request body returns 409 Conflict — it's almost always a client bug.
Only successful creates are stored; if a request fails validation, retrying with the same key re-runs it.

See the versioning & deprecation policy for the broader API stability contract.

Update a record

PUT /api/v1/projects/{project}/schemas/{schema}/records/{id}
Content-Type: application/json

{ "data": { "hp": 25 } }

Updates are a merge. Only the fields in the payload change, and omitted fields keep their existing values.

Delete a record

DELETE /api/v1/projects/{project}/schemas/{schema}/records/{id}

Irreversible.

Validation

Field values are validated against the schema's field configs on every write:

required fields must be present.
number fields enforce min, max, step, integer.
email fields validate the email format.
reference fields verify the target record exists.
select fields verify the value is in the options list.