API overview

Introduction to the PocketBase REST API

PocketBase provides a comprehensive REST API for managing your backend. The API allows you to perform CRUD operations on records, authenticate users, upload files, and manage your database in real-time.

Base URL

All API requests should be made to:

http://127.0.0.1:8090/api/

Replace with your actual PocketBase server URL in production.

Authentication

PocketBase supports multiple authentication methods:

• Admin authentication - For superuser access to all API endpoints
• User authentication - For auth collection records with specific permissions
• File tokens - For accessing protected files

Include the auth token in the Authorization header:

Authorization: Bearer YOUR_AUTH_TOKEN

Request format

The API accepts and returns JSON by default. For file uploads, use multipart/form-data.

Content-Type headers

• application/json - For JSON requests
• multipart/form-data - For file uploads

Response format

All responses are returned in JSON format with appropriate HTTP status codes.

Success responses

code · number

HTTP status code (200, 201, 204, etc.)

message · string

Human-readable success message

data · object

Response payload (varies by endpoint)

Error responses

code · number

HTTP error code (400, 401, 403, 404, 500, etc.)

message · string

Human-readable error message

data · object

Additional error details including validation errors

Common HTTP status codes

Code	Description
200	Success
201	Created
204	No Content (success with no response body)
400	Bad Request (validation error)
401	Unauthorized (missing or invalid auth token)
403	Forbidden (insufficient permissions)
404	Not Found
429	Too Many Requests (rate limit exceeded)
500	Internal Server Error

Pagination

List endpoints support pagination using query parameters:

page · number · default: "1"

Page number to retrieve

perPage · number · default: "30"

Number of items per page (max 500)

Pagination response

page · number

Current page number

perPage · number

Items per page

totalItems · number

Total number of items across all pages

totalPages · number

Total number of pages

items · array

Array of items for the current page

Filtering and sorting

You can filter and sort list results using query parameters:

filter · string

Filter expression (e.g., status='active' && created>'2023-01-01')

sort · string

Sort fields (prefix with - for descending, e.g., -created,title)

Expanding relations

Use the expand parameter to include related records:

expand · string

Comma-separated list of relation fields to expand (e.g., author,categories)

Field selection

Limit the fields returned in the response:

fields · string

Comma-separated list of fields to include (e.g., id,title,created)

Rate limiting

PocketBase implements rate limiting on API endpoints to prevent abuse. When you exceed the rate limit, you’ll receive a 429 status code.

Rate limits vary by endpoint and can be configured per collection.

CORS

Cross-Origin Resource Sharing (CORS) is enabled by default. You can configure allowed origins in the application settings.

Next steps

Authentication

Learn how to authenticate users and manage sessions

Records

Perform CRUD operations on collection records

Realtime

Subscribe to real-time data changes

Files

Upload and download files