Custom data collections overview

A collection is a custom data schema - the structured-data store behind forms, and usable on its own for anything you would otherwise add a table for.

Three levels, and the middle one is the part worth understanding:

curl https://api.console.buildbase.app/api/collections \
  -H "Authorization: $BUILDBASE_TOKEN"

Versions are the schema

Fields do not live on the collection. They live on a version, so changing the schema means publishing a new version rather than editing the old one - and records stay readable against the version they were written under.

A version is created with live: false. Setting live: true publishes it: it is refused with 400 "Fields must be added first" on a version with no fields, and it marks every older version of the collection deprecated, so one version is live at a time.

Field types

Each field on a version has one type: text, rich-text, email, link, color, number, integer, bool, date, select, multi-select, money, location and file. Note the name bool - not boolean.

Field types has what each one stores, its settings (lengths, ranges, patterns, choices, a money field's currency) and the errors a write can get.

Each field carries slug, title, helpText, type, required, and defaultValue. The slug is the key records are stored under.

File fields

A file field holds an image - JPEG, PNG, GIF, WebP or SVG - as one of your assets, never the bytes themselves. It has no default value; it has two settings instead:

Your plan's own per-file limit still applies below maxMb.

A record stores what the file is:

{
  "receipt": {
    "assetId": "6ace3b0e898d27ef4b7a6a30",
    "name": "receipt.png",
    "size": 900000,
    "mimeType": "image/png"
  }
}

A field whose maxFiles is above 1 stores a list of them, even when it holds one file:

{
  "photos": [
    {
      "assetId": "6ace3b0e898d27ef4b7a6a30",
      "name": "front.png",
      "size": 412000,
      "mimeType": "image/png"
    },
    {
      "assetId": "6ace3b0e898d27ef4b7a6a31",
      "name": "back.png",
      "size": 398000,
      "mimeType": "image/png"
    }
  ]
}

When you write a record yourself, send the asset by id - { "assetId": "..." } or the id alone - after uploading it; for a field that takes several files, send a list of them. The name, size and type are read back from the asset, whatever the request says, and the same asset sent twice is stored once. An empty string clears the field.

The write is refused with 400, naming the field, when an id is not one of your assets, when a list is sent to a field that takes one file, when there are more files than maxFiles, or when a file is larger than the field's maxMb - the same limit a visitor's file on a form is held to. A file over maxMb is named with its exact size and limit, and the answer carries maxBytes and tooLarge (records API). Files count toward your storage like any other upload, and deleting a record leaves its files in your assets.

Endpoints

Reading, writing and deleting records is covered in the records API.

How forms use this

A form is a collection plus a published version plus a public endpoint. Every submission becomes a record carrying collectionId, versionId, formId, and the submitted data.

That is why a form cannot exist without a published version, and why changing a form's fields means publishing a new collection version.

The one difference: form submissions arrive through the public endpoint, which needs no token. Everything on this page does.

Next Steps

• Field types - what each type stores and checks.
• Records API - read and delete stored records.
• Forms - collect records from a public endpoint.