REST API

Every action in the Celerp interface is a REST endpoint - the same API the UI uses internally. Automate workflows, connect other systems, or build your own tools. The API runs locally with your data; nothing is sent to the cloud.

Authentication

Celerp uses short-lived JSON Web Tokens. Log in with your Celerp email and password to get an access token, then send it as a Bearer header on every request.

1. Log in

curl -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "your-password"}'

The response contains two tokens:

{
  "access_token": "eyJhbGciOiJI...",
  "refresh_token": "eyJhbGciOiJI..."
}

2. Call the API with the token

curl http://localhost:8000/items \
  -H "Authorization: Bearer eyJhbGciOiJI..."

• The token identifies your user, role and company, so requests are automatically scoped to that company - no extra header needed.
• Access tokens last up to 24 hours. When one expires, get a fresh pair by POSTing your refresh_token to /auth/token/refresh.
• Belong to more than one company? List them with GET /auth/my-companies, then get a token scoped to another with POST /auth/switch-company/{company_id}.

Making requests

All endpoints live under your API server's address (http://localhost:8000 on a pip install, as in the examples below) and return JSON. List endpoints return an items array and a total count:

curl "http://localhost:8000/items?limit=20&offset=0" \
  -H "Authorization: Bearer $TOKEN"

{
  "items": [
    { "id": "item:...", "sku": "WIDGET-001", "name": "Widget", "quantity": 42 }
  ],
  "total": 142
}

Pagination: pass ?limit= (default 50) and ?offset=. Most list endpoints also accept a q= search term and column filters (e.g. ?status=available).

Creating data

POST JSON to create records. Writes return the new entity's id (and the underlying event_id - every change in Celerp is an event).

curl -X POST http://localhost:8000/crm/contacts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "email": "[email protected]",
    "contact_type": "customer",
    "idempotency_key": "acme-2026-06-21"
  }'

Conventions

• Errors non-2xx responses return {"detail": "..."} with a standard HTTP status code.
• Rate limits 60 requests/minute per IP by default; login is capped at 10/minute. Exceeding a limit returns 429.
• Permissions endpoints are gated by your role: viewer → operator → manager → admin → owner.
• Company scope every request acts on the company in your token; switch companies to act on another.

Common endpoints

A small slice to get you started. Every module adds its own - the full list is in the OpenAPI schema below.

Full reference by area

Every endpoint the running API serves, grouped by area. Each page lists the method, path, parameters, request and response shapes, and an example call.

Explore the full API

The complete, always-current reference is the OpenAPI 3.1 schema your own instance generates:

GET http://localhost:8000/openapi.json

Load it into any OpenAPI tool - Postman, Insomnia, Swagger UI, or a client generator - to browse every endpoint and model, try requests, and generate a typed client in your language. Celerp ships the schema itself rather than a hosted docs page, so your API surface stays private to your instance.