API overview

The PurrOS REST API gives other systems access to everything the web interface can do. Its main job is bringing data in; webhooks send changes back out.

The PurrOS REST API gives other systems access to everything the web interface can do. Its main job is bringing data in from point-of-sale systems, online stores, timeclocks, HR tools and other services. Webhooks send changes back out.

Base URL

https://<your-purros>/api/v1

Format

JSON (UTF-8). Money and quantities are decimal strings.

Spec

GET /api/v1/openapi.json (OpenAPI 3.1), with interactive docs at /docs/api on your server.

SDK

@purros/sdk for TypeScript Planned. For other languages, generate a client from the OpenAPI spec.

The spec on your server only contains endpoints of enabled features. Endpoints of switched-off features return 404 feature_disabled.

Quickstart

Get a key

Register an integration to get an integration key limited to the scopes it declares, or create a personal key with POST /api/v1/auth/api-keys if your role has api_keys.personal. Keys look like pk_live_… and are shown once.

Check who you are

curl https://erp.example.com/api/v1/me \
  -H "Authorization: Bearer $PURROS_KEY"

GET /me describes the calling key. For a person, GET /auth/session returns their role, permissions and assignments.

Read something

curl "https://erp.example.com/api/v1/locations?limit=50" \
  -H "Authorization: Bearer $PURROS_KEY"

{
  "data": [{ "id": "loc_01J8Z…", "name": "Store 101", "externalId": "101", "timezone": "America/Chicago" }],
  "nextCursor": null,
  "hasMore": false
}

Send data in

Most traffic is batched ingestion, idempotent on (source, externalId):

curl -X POST https://erp.example.com/api/v1/sales/transactions:batch \
  -H "Authorization: Bearer $PURROS_KEY" -H "Content-Type: application/json" \
  -d '{"source": "pos:store-101", "transactions": [ … ]}'

See Data ingestion for the rules and full examples.