Platform entities

Schema-driven apps store their data as typed entities — records validated against the app's own field definitions, not a generic document blob. This API lists, reads, creates, updates, and deletes entities for any app registered on the platform, and lets you introspect an app's schema before you write to it.

Concept

Response envelope

Entity read/write operations return an envelope shaped differently from the rest of the API — always check ok before reading data:

{ "ok": true, "data": { "id": "ent_123", "values": { "name": "Alice" } } }

{ "ok": false, "error": { "kind": "not_found", "message": "..." } }

error.kind is one of not_found, validation, conflict, and a few others. Passing any window parameter switches list responses to { "data": [...], "total": 42, "cursor": "..." } — pass the returned cursor back unchanged to get the next page; changing the sort or filters resets paging to the first window.

Look up an app's schema

curl -sf "https://api.falcata.io/api/v1/platform/apps/my-app/schema" \
  -H "Authorization: Bearer $FURNACE_TOKEN" | jq '.data.entities | keys'

List entities

curl -sf "https://api.falcata.io/api/v1/platform/apps/my-app/entities/contacts" \
  -H "Authorization: Bearer $FURNACE_TOKEN" | jq '.data[] | {id, name: .values.name}'

Filter, sort, and page a window — filters is a URL-encoded JSON array of {id, field, operator, values}. Supported operators: contains, equals, not_equals, in, not_in, starts_with, ends_with. Active filters combine with AND; an empty values array is inactive.

FILTERS='[{"id":"status:in","field":"status","operator":"in","values":["active","pending"]}]'
curl -sfG "https://api.falcata.io/api/v1/platform/apps/my-app/entities/contacts" \
  -H "Authorization: Bearer $FURNACE_TOKEN" \
  --data-urlencode "filters=$FILTERS" \
  --data-urlencode 'sort_key=name' \
  --data-urlencode 'sort_dir=asc' \
  --data-urlencode 'limit=50' | jq '{data, total, cursor}'

Create, update, and delete an entity

# Create — invalid fields return { ok: false, error: { kind: "validation" } }
curl -sf -X POST "https://api.falcata.io/api/v1/platform/apps/my-app/entities/contacts" \
  -H "Authorization: Bearer $FURNACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane Doe","email":"jane@example.com"}' \
  | jq 'if .ok then .data.id else .error end'

# Update
curl -sf -X PATCH "https://api.falcata.io/api/v1/platform/apps/my-app/entities/contacts/$ENTITY_ID" \
  -H "Authorization: Bearer $FURNACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@new-example.com"}'

# Delete
curl -sf -X DELETE "https://api.falcata.io/api/v1/platform/apps/my-app/entities/contacts/$ENTITY_ID" \
  -H "Authorization: Bearer $FURNACE_TOKEN"

If a create or update fails validation, the response tells you which field failed and why — fix the field and resend; nothing is partially written.

List and register apps

# All namespaces registered on the platform
curl -sf "https://api.falcata.io/api/v1/platform/namespaces" \
  -H "Authorization: Bearer $FURNACE_TOKEN" | jq '.data[]'

# Create a new schema-backed app
curl -sf -X POST "https://api.falcata.io/api/v1/platform/apps" \
  -H "Authorization: Bearer $FURNACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"slug":"my-app","name":"My App"}' | jq '.data'

Everything else — SDL artifact authoring, version snapshots, and app settings — in the full reference.