# Records API

Read records for a collection by slug, and delete them by id.

Records are read by collection **slug**, not id — which makes the read path
stable across environments where ids differ.

```bash
curl -G https://api.console.buildbase.app/api/collections/data/contact-requests \
  -H "Authorization: $BUILDBASE_TOKEN" \
  --data-urlencode 'latest=true' \
  --data-urlencode 'version=1'
```

Returns every record for the resolved version, unpaginated.

> **Note:**
  **Both `latest` and `version` are required**, even though only one is used.
  The query schema rejects anything else, so omitting `version` when
  `latest=true` returns `400` — pass a number anyway. No other query parameters
  are accepted, including the usual `$page` and `$limit`.


## Choosing a version

| Query                    | Reads                                   |
| ------------------------ | --------------------------------------- |
| `latest=true&version=1`  | The newest version, whatever its number |
| `latest=false&version=3` | Version number 3 specifically           |

`latest=true` is what you want in an application — it follows schema changes
automatically. Pin a number when you are migrating and need the old shape.

Failures are `404`:

| Condition                    | Response                                                    |
| ---------------------------- | ----------------------------------------------------------- |
| No collection with that slug | `{"error": true, "message": "not found collection:<slug>"}` |
| No version with that number  | `{"error": true, "message": "not found version:<n>"}`       |

## The response

An array of record documents. Each carries the submitted values under `data`,
keyed by field slug, plus the version it was written against:

```json
[
  {
    "_id": "665f…",
    "collectionId": "664a…",
    "versionId": "664b…",
    "formId": "664c…",
    "data": { "email": "alice@example.com", "message": "Interested" },
    "createdAt": "2026-08-15T09:12:44.108Z"
  }
]
```

`formId` is present only on records created through a
[form submission](/forms/overview).

> **Note:**
  This endpoint returns **every** record for the version with no pagination. On
  a collection behind a busy public form that grows without bound. Read it from
  a background job rather than a request handler, and prefer the paginated admin
  list endpoints if you need to page.


## Deleting a record

```bash
curl -X DELETE \
  https://api.console.buildbase.app/api/collections/$COLLECTION_ID/versions/$VERSION_ID/records/$RECORD_ID \
  -H "Authorization: $BUILDBASE_TOKEN"
```

Records are nested under their version, so deletion needs all three ids. There
is no bulk delete.

## Type coercion

Records store what was sent. The public form endpoint validates `number`,
`email`, `link`, and `date`, but a form submitted with `FormData` sends
everything as a string — so `"12"` rather than `12` is a normal thing to find in
`data`.

`bool` fields are not validated at all
([why](/forms/overview)), so treat those as untrusted when reading records back.

Coerce on read, or coerce before submitting — see
[custom forms](/forms/custom-forms).

## Next Steps

- [Collections overview](/collections/overview) — schemas and versions.
- [Forms](/forms/overview) — the public write path into a collection.