Basket DB API

Collections and records over REST: every endpoint, with examples.

Collections

Method	Path	Key	Does
GET	`/v1/projects/{project}/collections`	public	List collections with their fields and revision.
POST	`/v1/projects/{project}/collections`	secret	Create a collection.

curl -X POST -H 'Authorization: Bearer basket_secret_…' \
  -d 'name=messages' \
  -d 'fields={"body":{"type":"text","required":true},"sender_id":{"type":"text","required":true}}' \
  https://cloud.flaresinc.com/v1/projects/prj_…/collections

# 201
{ "collection": { "name": "messages", "fields": {…}, "revision": 1, "created_at": "…" } }

Records

Method	Path	Does
GET	`/collections/{collection}/records`	Query. Parameters →
POST	`/collections/{collection}/records`	Create.
GET	`/collections/{collection}/records/{id}`	Fetch one.
PATCH	`/collections/{collection}/records/{id}`	Update. Send `version` for optimistic concurrency.
DELETE	`/collections/{collection}/records/{id}`	Delete.

All record operations are governed by security rules; a public key alone grants nothing a rule refuses.

Query

curl -G 'https://cloud.flaresinc.com/v1/projects/prj_…/collections/messages/records' \
  -H 'Authorization: Bearer basket_public_…' \
  -H 'X-Basket-User-Token: eyJ…' \
  --data-urlencode 'where=[["room_id","==","r_42"]]' \
  --data-urlencode 'orderBy=created_at' --data-urlencode 'direction=desc' \
  --data-urlencode 'limit=50'

# 200
{ "records": [ { "id": "rec_…", "version": 3, "created_at": "…", "updated_at": "…",
                 "body": "Hello", "sender_id": "usr_…" } ],
  "cursor": "eyJ…" }

Create

curl -X POST 'https://cloud.flaresinc.com/v1/projects/prj_…/collections/messages/records' \
  -H 'Authorization: Bearer basket_public_…' \
  -H 'X-Basket-User-Token: eyJ…' -H 'Content-Type: application/json' \
  -d '{"data":{"body":"Hello","sender_id":"usr_…"}}'
# 201 { "record": { "id": "rec_…", "version": 1, … } }

Update with a version

curl -X PATCH '…/records/rec_…' \
  -H 'Authorization: Bearer basket_public_…' -H 'Content-Type: application/json' \
  -d '{"data":{"read":true},"version":3}'
# 200 on success; 409-style refusal if the record moved on without you

Subscribing

POST /v1/projects/{project}/collections/{collection}/subscribe
     {where?, snapshot?, limit?}

Called by the realtime gateway on a client's behalf; it returns the resolved, rule-checked predicate. Realtime protocol →

Minting a user token

POST /v1/projects/{project}/auth/tokens     {user_id, claims?, expires_in?}    # secret key

For applications whose users live elsewhere. Applications using Flares Auth get tokens from the Auth endpoints instead.