Skip to content
Nevela 0.33.1: New: customers get a shop in the mobile app, each sees only their own orders, and an administrator manages people and roles from the phone. Build it in the new drinks-app tutorial.A drinks app on the phone

REST API

Every resource gets the same set of endpoints. They follow the format Flare’s client expects, so the dashboard works against them unchanged, and you can call them from anything else that speaks HTTP.

All paths below are under the prefix /api. Send Accept: application/json on every request.

Every resource endpoint needs a token. The endpoints that get you one (a password, a passkey, an emailed link or code) do not: they are listed under Every auth endpoint. The Authentication guide describes what each is for.

Terminal window
curl -X POST http://127.0.0.1:8000/api/auth/token \
-H "Accept: application/json" -H "Content-Type: application/json" \
-d '{"email": "admin@example.com", "password": "your-password"}'
{
"token": "1|x8Jq…",
"expiresAt": "2026-10-20T09:15:00.000000Z",
"refreshToken": "kq0…",
"refreshExpiresAt": "2026-10-27T09:00:00.000000Z",
"user": {
"id": "1", "name": "Admin", "email": "admin@example.com",
"roles": ["ADMIN"], "permissions": ["products.create", "products.view", "…"], "isAdmin": true
}
}

The response status is 201. Wrong credentials give 401 with code: INVALID_EMAIL_OR_PASSWORD, and the same answer whether or not the address has an account. Ten attempts a minute are allowed per account.

deviceName is an optional third field that names the device.

The token works until expiresAt, 15 minutes unless set otherwise. refreshToken gets a new one.

Terminal window
curl -X POST http://127.0.0.1:8000/api/auth/refresh \
-H "Accept: application/json" -H "Content-Type: application/json" \
-d '{"refreshToken": "kq0…"}'

The answer has a new token, expiresAt, refreshToken and refreshExpiresAt. Keep the new refresh token and drop the old one, which won’t work again: presented later, it is taken as stolen and the sign-in ends. Within a minute of the swap it is a second request that set out at the same moment, and gets a token with "refreshToken": null; keep the one you have.

A sign-in that has ended answers 401 with a code:

code Why
SESSION_IDLE Not refreshed for 7 days.
SESSION_EXPIRED 30 days have passed since it began.
SESSION_REPLAYED A refresh token that was already swapped was used again.
SESSION_REVOKED Signed out, from this device or another, or the account was switched off.

refreshExpiresAt is when the sign-in ends if it isn’t refreshed again. It is null when there are no limits.

Terminal window
curl http://127.0.0.1:8000/api/products -H "Accept: application/json" -H "Authorization: Bearer 1|x8Jq…"

POST /auth/token answers 200 with no token:

{ "twoFactor": true, "challenge": "Lh8IN0Fh…", "methods": ["totp", "email", "backup"] }

Finish with the code. method is totp (an authenticator app), email or backup:

Terminal window
curl -X POST http://127.0.0.1:8000/api/auth/two-factor/verify \
-H 'Accept: application/json' -H 'Content-Type: application/json' \
-d '{"challenge": "Lh8IN0Fh…", "method": "totp", "code": "482913"}'

That answers 201 with the token. For email, ask for the code first with POST /auth/two-factor/send and the same challenge. The challenge lasts ten minutes and allows five wrong codes. Only the methods the answer listed are accepted, and an authenticator code works once.

An emailed sign-in link or code can get the same answer, when the account has an authenticator app: methods then leaves out email.

All are under /api/auth. The ones marked 🔒 need a token.

Endpoint Does
GET /config Which sign-in methods are switched on.
POST /token Sign in with email and password.
POST /refresh A new pair for refreshToken. See Keep it going.
POST /two-factor/send, /two-factor/verify The second step of a password sign-in.
POST /passkey/options, /passkey Sign in with a passkey.
POST /magic-link, /magic-link/verify Email a sign-in link; sign in with its token.
POST /email-code, /email-code/verify Email a sign-in code; sign in with email and code.
POST /register Create an account, when registration is on.
POST /email/send, /email/verify Send the verification email; verify with email and code.
POST /password/forgot, /password/reset Email a reset link; set newPassword with its token.
POST /oauth/{provider}/start, /oauth/{provider}/callback Sign in with google or github: where to send the browser, then the code it came back with. See how it works.
🔒 GET /me, PATCH /me The signed-in user; change name or avatar.
🔒 PUT /avatar?name=me.jpg Upload a profile picture. The body is the file.
🔒 POST /password Change the password: currentPassword, newPassword.
🔒 POST /close Close your own account, with password. It is kept, and can be restored.
🔒 GET /sessions, DELETE /sessions, DELETE /sessions/{id} List devices; sign out the others, or one.
🔒 POST /two-factor/enable, /confirm, /disable, /backup-codes Set up and manage the second step.
🔒 GET /passkeys, POST /passkeys/options, POST /passkeys, PATCH/DELETE /passkeys/{id} List, add, rename and remove passkeys.
🔒 GET /social, DELETE /social/{id} The Google and GitHub accounts connected to yours; disconnect one.
🔒 DELETE /token Sign out: the sign-in ends, and its tokens stop working.

An error has a code beside its message, such as INVALID_EMAIL_OR_PASSWORD, INVALID_TWO_FACTOR_CODE, OTP_EXPIRED, TOO_MANY_ATTEMPTS, or ACCOUNT_CLOSED for an account that was closed. A method that is switched off answers 404. Attempts are limited to ten a minute per account, after which the answer is 429.

Request Response
GET /auth/me 200 { "user": { id, name, email, role, roles, permissions, isAdmin, emailVerified, twoFactorEnabled, avatar, avatarFile, image }, "session": { id } }. role is the first of roles, for code written when an account had one.
DELETE /auth/token 204. The token used for the request stops working.

Using products as the example:

Request What it does Success
GET /products List records 200 { data, meta }
GET /products/{id} One record 200 the record
POST /products Create 201 the record, with a Location header
POST /products/_bulk Create several 201 { created, data }
PATCH /products/{id} Change some fields 200 the record
PUT /products/{id} Replace the record 200 the record
DELETE /products/{id} Delete: to the trash, where it can be restored 204
GET /products/_stats Counts for dashboards 200 { total, current, previous, values }
GET /products/_insights Counts per period and per choice, for charts 200 { total, unit, series, breakdown }
{
"id": "01a0fd2e-fc37-7264-b9ef-d52f2946a935",
"name": "Widget",
"sku": "W-1",
"price": 19.5,
"active": true,
"kind": "stock",
"notes": null,
"createdAt": "2026-10-02T15:15:10.000000Z",
"updatedAt": "2026-10-02T15:15:10.000000Z"
}

Keys are camelCase, matching the descriptor. The id is a string: a UUID, or digits for a resource with integer ids. Dates are YYYY-MM-DD and timestamps are ISO 8601.

GET /products?page=2&perPage=25&sort=-price&q=lamp&filter[kind]=stock
Parameter Meaning
page Page number, from 1. Default 1.
perPage Records per page. Default 25, at most 100.
sort A field name to sort by. Prefix with - for descending. createdAt and updatedAt work too. Default -createdAt. text fields cannot be sorted.
q Search text. Matches any string field that contains it.
filter[field] Keep records where the field equals the value. Use true or false for booleans. An empty value or null matches records where an optional field is empty. text fields cannot be filtered.
{
"data": [ { "id": "…", "name": "Lamp" } ],
"meta": { "page": 2, "perPage": 25, "total": 137, "totalPages": 6 }
}

With curl, add -g so the square brackets in filter[kind] are sent as written.

Send the fields as JSON:

Terminal window
curl -X POST http://127.0.0.1:8000/api/products \
-H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Bearer …" \
-d '{"name": "Lamp", "sku": "L-1", "price": 42, "active": true, "kind": "stock"}'

The difference between the two ways to update:

Method Fields you leave out
PATCH Stay as they are. Only the fields you send are checked and changed.
PUT Optional fields are cleared. Required fields must be sent.

A key that is not a field of the resource is rejected with 422 rather than ignored, so a misspelt field name does not pass unnoticed. id and createdAt may be included and are ignored.

Send back the updatedAt you read with a PATCH or PUT, and the change is made only if nobody has saved the record since. Otherwise nothing is changed, and the answer is a 409 with the record as it is now:

{
"error": "Someone else saved this product after you read it, so nothing was changed. Send your change again with the updatedAt it has now.",
"code": "CHANGED_SINCE_READ",
"current": { "id": "…", "name": "Lamp", "price": 45, "updatedAt": "2026-10-02T15:20:41.000000Z" }
}

Compare current with what you read, put your change on top of it, and send it again with its updatedAt. The dashboard’s edit form does this for you. Leave updatedAt out and the change is made whatever happened in between, as it always was.

A change to a record’s lines is a change to the record: it moves the record’s updatedAt too. For a record with lines, current has them as items, because the items you send replace the whole list.

Terminal window
curl -X POST http://127.0.0.1:8000/api/products/_bulk \
-H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Bearer …" \
-d '{"items": [{"name": "Lamp", "sku": "L-1", "price": 42, "active": true, "kind": "stock"}, {"name": "Desk", "sku": "D-1", "price": 180, "active": true, "kind": "stock"}]}'

Every row is checked with the rules for creating one, before anything is written, and they are saved in one transaction. So the answer is all of them (201 { "created": 2, "data": [ … ] }), or none and the rows that were wrong:

{
"error": "Nothing was created: row 2 needs fixing.",
"rows": [{ "row": 2, "issues": [{ "path": "sku", "message": "The same as row 1. Each one needs its own." }] }]
}

Rows are numbered from 1. Two rows of one request can’t share a unique value. At most 500 rows a request (bulk_max in config/nevela.php); for more, import a file from the dashboard. It takes the same permission as creating one.

GET /products/_stats?field=kind&days=7
{ "total": 1000, "current": 118, "previous": 104, "values": { "digital": 489, "stock": 511 } }
Key Meaning
total All records.
current Records created in the last days days.
previous Records created in the days before that.
values Records per value of field. Empty when field is not given.

days is 1 to 365, default 7. field must be an enum or boolean field.

GET /products/_insights?unit=week&filter[kind]=digital

What the dashboard’s insights panel is drawn from.

Part of the answer What it is
total Everything the request matches, whenever it was created.
series How many were created in each period, oldest first: [{ "bucket": "2026-10-05", "count": 3 }, … ]. A period with nothing in it is there, as zero.
breakdown For each enum and yes/no field (the first four), how many records hold each choice: [{ "field": "kind", "kind": "enum", "slices": [{ "value": "stock", "count": 22 }, … ] }]. Every choice is listed, in the field’s own order.

unit is day (the last 30 days, the default), week (the last 26 weeks, each called by its Monday) or month (the last 12 months, as 2026-10).

It takes the list’s q and filter[…], so the counts are of the same records a list request with those parameters returns. page, perPage and sort are accepted and change nothing. It takes the permission to view the resource. Days are counted in the app’s timezone (config/app.php).

A deleted record is kept for 30 days (trash.days) and answers 404 everywhere above until it is restored. These are the same for every resource, by its slug:

Request What it does Success
GET /_nevela/trash How long things are kept, and how many of each resource are deleted 200 { days, resources }
GET /_nevela/trash/products The deleted products, the latest deletion first. Takes page and perPage. 200 { data, meta }
POST /_nevela/trash/products/{id}/restore Put one back 200 { id, restored }
DELETE /_nevela/trash/products/{id} Remove one for good 204
DELETE /_nevela/trash/products?confirm=products Remove every deleted product for good 200 { removed, kept }
GET /_nevela/trash/_status Which resources have a trash the caller may use. Counts nothing. 200 { days, resources }
{
"data": [
{ "id": "01a0fd2e-…", "label": "Lamp", "deletedAt": "2026-10-09T12:00:00.000000Z", "expiresAt": "2026-11-08T12:00:00.000000Z" }
],
"meta": { "page": 1, "perPage": 25, "total": 1, "totalPages": 1 }
}

label is the record’s title, as a list shows it. expiresAt is when it is removed for good, and null when trash.days is off.

Each takes the permission to delete the resource; a resource the caller may not delete is left out of the first and last, and answers 403 on the rest. A resource whose table has no trash yet answers 404.

Refusal Status code
Restoring a record whose required parent is in the trash too 409 PARENT_IN_TRASH
Removing a record that deleted records still belong to 409 STILL_REFERENCED
Emptying without confirm set to the resource’s slug 422 CONFIRM

Emptying removes what it can and counts the rest in kept.

A unique value held by a deleted record is still taken. Creating another with it answers 422, with a message that says the value belongs to a record in the trash.

The dashboard’s bell. Each person reads and marks only their own; see Notifications.

Request What it does Success
GET /_nevela/notifications The latest 30, newest first, how many are unread, and for an administrator what is wrong with the app 200 { items, unread, conditions }
POST /_nevela/notifications/read Mark one read ({ "id": "…" }), or all of them (no body). Another person’s id changes nothing. 200 { read }
GET /_nevela/activity Who created, changed, deleted, restored or removed for good which records, newest first, on the resources the caller may view. Takes resource, action, user, page and perPage (at most 100). Needs activity.view; 403 without it. 200 { data, meta }

An activity entry is { id, action, resource, label, pluralLabel, slug, count, title, recordId, url, user: { id, name }, at, startedAt }. The same thing done by one person within two minutes is one entry, and count is how many times it was done: usually that many records, but deleting the same record twice in that time counts two. title and recordId are set when the count is one. url is where to look when the entry was written: the record, the list, or for a deletion the trash (the list, for someone who may not delete). It is null on an entry whose action is purged; an older entry’s link can lead to a record that has since gone. Before php nevela migrate it answers 409 with code: "MIGRATION_NEEDED".

{
"items": [
{ "id": "019a2f…", "kind": "form.received", "title": "3 new enquiries", "body": null, "url": "/dashboard/enquiries", "tone": "info", "count": 3, "read": false, "at": "2026-10-26T14:05:00+00:00" }
],
"unread": 1,
"conditions": [
{ "id": "release", "title": "Nevela 0.20.0 is out", "body": "This app is on 0.19.2. Run php nevela upgrade to move to it.", "tone": "info", "url": "https://nevela-docs.vercel.app/reference/changelog/" }
]
}

conditions is always empty for someone who isn’t an administrator.

A belongsTo field is the related record’s id, in what you send and in what comes back:

{ "name": "Smart Kettle", "categoryId": "01a10804-7b04-72d6-aabf-a2113b9b6bc5" }

An id that is not a record of that resource is a 422. Filter a list by it with filter[categoryId]=….

Deleting a record that others are required to belong to is a 409:

{ "error": "8 products belong to this category. Move or delete them first." }

A resource with line items sends its lines with one record, as items, and takes them back the same way: a line with its id is changed, one without is added, and one left out is removed. A mistake in a line is named by its place, items.1.quantity.

Method Path Does
PUT /api/_nevela/uploads/{Resource}/{field}?name=kettle.jpg Stores a file. The request body is the file itself.
GET /api/_nevela/files/{key} The stored file. No token needed.
GET /api/_nevela/profiles The image profiles and their renditions.

An upload answers 201 with the file’s details:

{
"key": "products/image/2026/10/778e5b3c-5a55-4b18-bdfa-4da5f1151a93-kettle.webp",
"url": "http://127.0.0.1:8000/api/_nevela/files/products/image/2026/10/778e5b3c-5a55-4b18-bdfa-4da5f1151a93-kettle.webp",
"name": "kettle.jpg",
"mime": "image/webp",
"size": 87040,
"width": 1000,
"height": 750,
"optimised": true,
"renditions": {
"thumb": { "url": "…-kettle.thumb.webp", "width": 300, "height": 300, "size": 22118 }
}
}

Send the key as the field’s value when you create or change the record. A record comes back with the key in the field and these details beside it, as <field>File (imageFile for image), or null when the field is empty.

Status When
404 The resource, or a file field of that name, does not exist.
413 The file is larger than uploads.max_bytes.
422 The contents are not a kind the field accepts, or do not match what the file was sent as.

A record refuses a key that was not uploaded to that same field.

Every error is JSON with an error message.

Status When Body
400 A bad list parameter, such as sorting by an unknown field { error, issues: [{ param, message }] }
401 No token, or one that is no longer valid { error }
403 The policy says no: the person’s roles don’t include the permission { error }
404 No record with that id { error }
409 A unique value was taken between validation and saving { error, field }
409 Someone else saved the record after the updatedAt you sent { error, code: "CHANGED_SINCE_READ", current }
422 Validation failed { error, issues: [{ path, message }] }
429 Too many requests { error }

A validation error names each field:

{
"error": "Validation failed.",
"issues": [
{ "path": "name", "message": "The name field is required." },
{ "path": "sku", "message": "The sku has already been taken." }
]
}

A duplicate value in a unique field is normally a 422 like the one above, because the validation rule catches it. The 409 only happens when two requests race.

GET /_nevela/ping

Needs no token. Returns { "nevela": "0.1.3", "app": "3cd733775782" }: the Nevela version, and a short id for this installation. It is how nevela status and the dashboard tell this app’s API from another program on the same port.

GET /_nevela/resources

Returns { "data": [ … ] } with every descriptor. Tooling can use it to check that the web app and the API describe the same resources.

routes/nevela.php is loaded under the same prefix and middleware. Add routes below its generated block and they get the token check and the same error format:

// nevela:generated:end
Route::post('products/{product}/archive', [ProductController::class, 'archive']);