Records

Read and write the records of a collection. Every action is checked against the collection's rules; superusers bypass them.

List records

Returns a page of records. Records the listRule does not match are left out.

SDK

const page = await nb.collection("posts").getList(1, 20, {
  filter: nb.filter("published = true && title ~ {:q}", { q: "next" }),
  sort: "-created",
  expand: "author",
});

curl

curl -G https://app.example/api/nextbase/collections/posts/records \
  --data-urlencode 'filter=published = true && title ~ "next"' \
  --data-urlencode 'sort=-created' \
  --data-urlencode 'expand=author'

GET /collections/{collection}/records

Path parameters

Param	Type	Description
collection	string	Collection name or id

Query parameters

Param	Type	Description
page	number	Optional. Page number, from 1. Default 1.
perPage	number	Optional. Records per page, 1 to 1000. Default 30.
filter	string	Optional. A filter.
sort	string	Optional. Comma-separated fields, - for descending, e.g. -created,title. Default -created when the collection has that field.
expand	string	Optional. Relations to load, e.g. author,comments_via_post.author. Up to 6 levels.
fields	string	Optional. Fields to return, e.g. id,title,expand.author.name.
skipTotal	boolean	Optional. true skips counting; totals are then -1.

Responses

200

{
  "page": 1,
  "perPage": 20,
  "totalItems": 2,
  "totalPages": 1,
  "items": [
    {
      "collectionId": "c1a2b3c4d5e6f7g",
      "collectionName": "posts",
      "id": "k3j2h1g9xa0b1c2",
      "title": "Next.js tips",
      "published": true,
      "author": "u7v8w9x0y1z2a3b",
      "created": "2026-10-19T09:30:00.000Z",
      "expand": {
        "author": { "collectionName": "users", "id": "u7v8w9x0y1z2a3b", "name": "Ann" }
      }
    }
  ]
}

400

{ "status": 400, "message": "Invalid filter: Unknown field \"titel\".", "data": {} }

403

{ "status": 403, "message": "Only superusers can perform this action.", "data": {} }

Returned when listRule is null.

View a record

Returns one record. A record the viewRule does not match is a 404.

SDK

const post = await nb.collection("posts").getOne("k3j2h1g9xa0b1c2", {
  expand: "author",
});

curl

curl 'https://app.example/api/nextbase/collections/posts/records/k3j2h1g9xa0b1c2?expand=author'

GET /collections/{collection}/records/{id}

Path parameters

Param	Type	Description
collection	string	Collection name or id
id	string	Record id

Query parameters: expand and fields, as for listing.

Responses

200

{
  "collectionId": "c1a2b3c4d5e6f7g",
  "collectionName": "posts",
  "id": "k3j2h1g9xa0b1c2",
  "title": "Next.js tips",
  "published": true,
  "created": "2026-10-19T09:30:00.000Z"
}

403

{ "status": 403, "message": "Only superusers can perform this action.", "data": {} }

404

{ "status": 404, "message": "Record not found.", "data": {} }

Create a record

Creates a record. The createRule is checked against the new record before it is inserted.

SDK

const post = await nb.collection("posts").create({
  title: "Hello",
  author: "u7v8w9x0y1z2a3b",
});

curl

curl -X POST https://app.example/api/nextbase/collections/posts/records \
  -H 'authorization: Bearer <token>' \
  -H 'content-type: application/json' \
  -d '{"title":"Hello","author":"u7v8w9x0y1z2a3b"}'

POST /collections/{collection}/records

Body: a JSON object of field values. id is optional: 15 characters from a-z0-9, generated when left out. For auth collections, also send password and passwordConfirm.

Query parameters: expand and fields, applied to the returned record.

Responses

200

The created record, as for viewing.

204

No body: the record was created, but the viewRule does not let the caller see it. The SDK returns null.

400

{
  "status": 400,
  "message": "Failed to create the record.",
  "data": {
    "title": { "code": "validation_required", "message": "Cannot be blank." },
    "author": { "code": "validation_missing_relation", "message": "No users record with id u7v8w9x0y1z2a3b." }
  }
}

Also returned, with no field errors, when the createRule does not match.

403

{ "status": 403, "message": "Only superusers can perform this action.", "data": {} }

Update a record

Changes the fields you send. A record the updateRule does not match is a 404, and the rule is checked before validation, so its errors never reveal a record the caller cannot change.

SDK

await nb.collection("posts").update("k3j2h1g9xa0b1c2", {
  title: "Hello again",
  "views+": 1,
});

curl

curl -X PATCH https://app.example/api/nextbase/collections/posts/records/k3j2h1g9xa0b1c2 \
  -H 'authorization: Bearer <token>' \
  -H 'content-type: application/json' \
  -d '{"title":"Hello again","views+":1}'

PATCH /collections/{collection}/records/{id}

Body: a JSON object of field values, and these modifiers:

Key	Field types	Effect
field+	number	adds the value
field-	number	subtracts the value
field+	multiple select or relation	appends values
+field	multiple select or relation	prepends values
field-	multiple select or relation	removes values

For auth collections, changing password needs passwordConfirm and oldPassword (unless the caller is a superuser or matches the manageRule). A password change signs out the record's other sessions.

Query parameters: expand and fields, applied to the returned record.

Responses

200

The updated record.

204

No body: the update succeeded, but the caller can no longer view the record.

400

{
  "status": 400,
  "message": "Failed to update the record.",
  "data": {
    "servings": { "code": "validation_out_of_range", "message": "Must be between 1 and ∞." }
  }
}

404

{ "status": 404, "message": "Record not found.", "data": {} }

Delete a record

Deletes a record and, through relation fields, deletes or clears the records that point at it (see Relations).

SDK

await nb.collection("posts").delete("k3j2h1g9xa0b1c2");

curl

curl -X DELETE https://app.example/api/nextbase/collections/posts/records/k3j2h1g9xa0b1c2 \
  -H 'authorization: Bearer <token>'

DELETE /collections/{collection}/records/{id}

Responses

204

No body.

400

{ "status": 400, "message": "The last superuser cannot be deleted.", "data": {} }

Also returned when clearing a reference would leave a required field empty.

404

{ "status": 404, "message": "Record not found.", "data": {} }