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": "you@example.com", "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 http://localhost:8000 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": "ap@acme.com",
    "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.

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.