REST API

Installation

The REST API is an optional package. Install it only in projects that need it:

composer require crudadmin/api

Token routes need the crudadmin/helpers authentication package as well. Without it, only the Swagger UI of signed in administrators is registered.

Endpoints

The API reads and writes rows through the same code as the administration. It applies the model permissions (read, insert, update, delete), scopeAdminRows(), validation, request mutators and uploads, history, admin rules and model events. A row hidden in the administration is not found by the API either. Models with $insertable, $editable or $deletable set to false refuse the same actions as in the administration.

Method	URL	Action
GET	`/admin/api/v1/models/{table}`	paginated rows
POST	`/admin/api/v1/models/{table}`	create a row, missing fields receive their `default` value
GET	`/admin/api/v1/models/{table}/{id}`	one row
PUT, PATCH	`/admin/api/v1/models/{table}/{id}`	update only the sent fields
DELETE	`/admin/api/v1/models/{table}/{id}`	delete a row
GET	`/admin/api/v1/models`	readable models with relations and allowed `operations`
GET	`/admin/api/v1/openapi.json`, `/admin/api/v1/openapi.yaml`	OpenAPI description of the accessible models
GET	`/admin/api/v1/models/{table}/scheme`, `/admin/api/v1/scheme`	OpenAPI description in YAML, of one or all models
POST	`/admin/api/v1/auth/login`	sign in and receive a token
GET	`/admin/api/v1/user`	signed in administrator

File fields are returned as URLs, multiple file fields as a list of URLs.

Tokens

POST /admin/api/v1/auth/login issues a Sanctum token. Send it as Authorization: Bearer {token}.

{ "email": "admin@example.com", "password": "…", "access": "write" }

`access`	Token
`read` (default)	only reads rows, the models list and the OpenAPI description; writes answer `403`
`write`	reads, creates, updates and deletes rows

Any other value answers 422 before the credentials are checked. The response lists the token abilities in data.token.abilities, e.g. ["api", "api:read"]. Clients which create, update or delete rows have to ask for "access": "write". The permissions of the administrator apply on top of the token: a write token of an administrator without the update permission of a model can not update it. /admin/api/v1/models and the OpenAPI description show only the operations the token and the permissions allow. Tokens of the REST API are valid only for /admin/api/v1/*. The administration refuses them with 403, so a leaked API token does not open the admin interface.

Ability	Allows
`api`	the REST API
`api:read`	GET endpoints of the REST API
`api:write`	POST, PUT, PATCH and DELETE of the REST API
`admin`	the administration (routes of the admin session reached with a bearer token)

Tokens with the * ability, created before v6 or by createToken() without abilities, keep access to both the REST API and the administration. Issue a token for your own integration with explicit abilities:

$token = $admin->createToken('erp-sync', \AdminApi\Auth\TokenAccess::abilities('read'))->plainTextToken;

OpenAPI and Swagger

/admin/api/v1/openapi.json describes every model the token may read: its columns and types, required fields, relations, and only the operations the administrator is allowed to use. Give it to API clients and AI agents, so they learn the models and the endpoints without further documentation. Limit it to some models with ?models=products,orders. Signed in administrators browse the same description in the Swagger UI at /admin/api/v1/docs. It loads the description from /admin/api/v1/docs/openapi.json with the admin session.

Responses

Responses follow Laravel API Resources. The list is paginated:

GET /admin/api/v1/models/orders?per_page=2

{
  "data": [
    { "id": 12, "number": "A-2026", "price": 120, "created_at": "2026-09-01T08:00:00.000000Z" },
    { "id": 13, "number": "A-2027", "price": 80, "created_at": "2026-09-02T09:30:00.000000Z" }
  ],
  "links": { "first": "…?page=1", "last": "…?page=5", "prev": null, "next": "…?page=2" },
  "meta": { "current_page": 1, "last_page": 5, "per_page": 2, "from": 1, "to": 2, "total": 10 }
}

Action	Status	Body
list	200	`{ data: [...], links, meta }`
one row, update	200	`{ data: {...} }`
create	201	`{ data: {...} }`
delete	204	empty
models	200	`{ data: [{ table, name, relations, operations }] }`
invalid parameter	400	`{ message }`
missing or invalid token	401	`{ message }`
missing permission or token ability	403	`{ message }`
unknown model or row	404	`{ message }`
validation	422	`{ message, errors: { field: [...] } }`

Rows contain the API columns of the model (id, foreign keys and fields) and the existing created_at, updated_at, published_at and _order. Password fields, inaccessible fields, $hidden attributes and table columns which are not fields (e.g. remember_token, logout_date, deleted_at) are never returned, selected, sorted or filtered. Passwords can only be written.

Query parameters

The parameters follow the conventions of spatie/laravel-query-builder (the JSON:API style).

Parameter	Example	Description
`filter`	`filter[status]=paid`	rows with the value
	`filter[status]=new,paid`	one of the values
	`filter[price]=>=10,<100`	operators `>`, `>=`, `<`, `<=`, `<>`, all conditions apply
	`filter[number]=~A-20`	contains
	`filter[paid_at]=null`, `filter[paid_at]=!null`	empty, not empty
	`filter[popular]=100`	scope of the model (`scopePopular($query, $minimum)`) with its parameter
`sort`	`sort=-created_at,number`	columns, a minus for descending order; by the primary key by default
`include`	`include=customer,items.product`	relations, a dot for nested relations (up to 3 levels)
	`include=itemsCount`	number of rows of a relation, as `items_count`
`fields`	`fields[orders]=number,price&fields[customers]=name`	returned columns by table, of the model and of included relations; keys matching the relations are added
`page`, `per_page`	`page=2&per_page=50`	page and its size, up to `admin.api.max_per_page` (100)
`selector`	`/models/orders/A-2026?selector=number`	find a row by another API column instead of the id

include and fields also apply to one row, and to the row returned after create and update. The parameters reach only what the API describes, the same for every token:

include accepts relations of the model: its belongsTo / belongsToMany fields, child models and parent models of $belongsToModel, by their camelCase names listed in /admin/api/v1/models. The administrator needs the read permission of the related model, and scopeAdminRows() of the related model limits the included rows as in the administration.
filter, sort and fields accept only the API columns and the timestamps above.
Scope filters apply only scopes declared on the model itself, internal scopes of CrudAdmin are not available.

Other values are refused with 400.

Customizing the response

app/Models/Order.php

public function scopeWithAdminApiResponse($query)
{
    $query->where('is_internal', false);
}

public function setAdminApiResponse()
{
    return $this->makeHidden('secret')->append('price_with_vat');
}

Requests are logged by default, see the api configuration.

Getting started

Upgrade guide

Admin interface

Validation

Frontend

Website

Installation

Endpoints

Tokens

OpenAPI and Swagger

Responses

Query parameters

Customizing the response

​Installation

​Endpoints

​Tokens

​OpenAPI and Swagger

​Responses

​Query parameters

​Customizing the response

Installation

Endpoints

Tokens

OpenAPI and Swagger

Responses

Query parameters

Customizing the response