REST API reference

NextBase serves a REST API under the route you mount it at, by default /api/nextbase. Requests and responses are JSON. Every path in this reference is relative to that.

Area	Paths
Records	/collections/{collection}/records
Auth	/collections/{collection}/auth-with-password, /session, /sessions
Collections	/collections (superusers)
Setup and health	/setup, /health

Authentication

Send the session token from signing in in the Authorization header (a "Bearer token"):

Authorization: Bearer <token>

or sign in with a session cookie, which the browser sends on its own. If both are present, the header wins.

• An invalid or expired Bearer token is a 401.
• An invalid cookie is removed and the request continues signed out.
• A write (POST, PATCH, DELETE) authenticated by the cookie must send an Origin header naming the same host, or it gets a 403. Browsers do this on their own.

Requests

Request bodies are JSON (Content-Type: application/json), up to 1 MiB.

Errors

Every error has the same shape:

{
  "status": 400,
  "message": "Failed to create the record.",
  "data": {
    "title": { "code": "validation_required", "message": "Cannot be blank." }
  }
}

data holds field errors, keyed by field and nested for nested input. code is stable and meant for programs; message is for people.

Status	Meaning
400	invalid input, a failed create rule, or a bad filter
401	missing or invalid credentials where they are required
403	the action needs a superuser, or a cross-site cookie write
404	not found, or hidden by a rule
405	method not allowed
409	conflict with a concurrent change; retrying works
413	request body too large
415	request body is not JSON
429	too many failed sign-in attempts
500	unexpected server error, logged on the server

Field error codes

Code	Meaning
validation_required	the value is empty
validation_invalid_value	the value is not allowed
validation_invalid_type	the value has the wrong type
validation_invalid_format	the value does not match the pattern
validation_invalid_email, validation_invalid_url	not an email or URL
validation_domain_not_allowed	the email or URL domain is not allowed
validation_length_out_of_range	text too short or too long
validation_out_of_range	number or date out of range
validation_not_integer	the number must be whole
validation_too_many	too many values selected
validation_too_large	JSON value too large
validation_not_unique	the value is already taken
validation_missing_relation	a related record does not exist
validation_values_mismatch	passwordConfirm differs from password
validation_invalid_old_password	oldPassword is missing or wrong
validation_forbidden	only superusers may change this field
validation_invalid_rule	a rule does not compile