API Reference¶

This section provides complete API documentation for litestar-admin, including both the REST API and Python API.

REST API¶

Complete REST API reference for litestar-admin. All endpoints are prefixed with /admin by default (configurable via AdminConfig.base_url).

{your-app-url}/admin/api

Most endpoints require authentication. Include the access token in the Authorization header:

Authorization: Bearer <access_token>

Alternatively, tokens can be sent via cookies if configured in your auth backend.

All responses use JSON format. Successful responses return the requested data directly. Error responses follow this structure:

{
  "detail": "Error message describing what went wrong",
  "status_code": 400
}

Method	Endpoint	Description
POST	`/api/auth/login`	Authenticate with credentials
POST	`/api/auth/logout`	End current session
POST	`/api/auth/refresh`	Refresh access token
GET	`/api/auth/me`	Get current user info

Method	Endpoint	Description
GET	`/api/dashboard/stats`	Get model statistics
GET	`/api/dashboard/activity`	Get recent activity

Method	Endpoint	Description
GET	`/api/models/{model}/export`	Export all records (CSV, JSON, XLSX)
POST	`/api/models/{model}/bulk/export`	Export selected records

Method	Endpoint	Description
POST	`/api/models/{model}/import/preview`	Preview CSV with auto-detection
POST	`/api/models/{model}/import/validate`	Validate with column mappings
POST	`/api/models/{model}/import/execute`	Execute batch import

Method	Endpoint	Description
POST	`/api/models/{model}/bulk/delete`	Bulk delete records
POST	`/api/models/{model}/bulk/{action}`	Custom bulk action

Code	Description
200	Success
201	Created (for POST creating new records)
400	Bad Request (invalid input)
401	Unauthorized (not authenticated)
403	Forbidden (insufficient permissions)
404	Not Found (model or record doesn’t exist)
422	Validation Error
429	Too Many Requests (rate limited)
500	Internal Server Error

When rate limiting is enabled, responses include these headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000

If the limit is exceeded, you’ll receive a 429 status code:

{
  "error": "Too Many Requests",
  "retry_after": 60
}

The API is fully documented with OpenAPI 3.0. Access the interactive documentation at:

These are provided by Litestar’s built-in OpenAPI support.

Class	Description
`AdminPlugin`	Main plugin implementing Litestar’s InitPluginProtocol
`AdminConfig`	Configuration dataclass for the admin panel
`ModelView`	Base class for model views with model binding
`BaseModelView`	Foundation class for model views
`ModelRegistry`	Registry for managing model views
`AdminService`	Service layer for CRUD operations

Class	Description
`JWTAuthBackend`	JWT-based authentication backend
`JWTConfig`	Configuration for JWT authentication
`AuthBackend`	Protocol for authentication backends
`AdminUser`	Protocol for admin user objects

Item	Description
`Permission`	Enum of available permissions
`Role`	Enum of available roles
`PermissionGuard`	Guard that checks permissions
`RoleGuard`	Guard that checks roles
`require_permission()`	Factory for permission guards
`require_role()`	Factory for role guards

Class	Description
`AuditAction`	Enum of auditable actions
`AuditEntry`	Single audit log entry
`AuditLogger`	Protocol for audit backends
`InMemoryAuditLogger`	In-memory audit logger
`audit_admin_action()`	Helper to create audit entries