API Reference

Base URL: https://app.proofwork.today/api/v1

Auth: Bearer token — generate from Settings → API Keys.

Authentication

All requests require a Bearer token in the Authorization header:

curl -s -H "Authorization: Bearer pw_..." https://app.proofwork.today/api/v1/account

API keys are created in the app under Settings → API Keys. The token is shown once — save it immediately.

Endpoints

Resource	List	Create	Get	Update	Archive	Restore
Account	—	—	`GET /account`	`PATCH /account`	—	—
Things	`GET /things`	`POST /things`	`GET /things/:id`	`PATCH /things/:id`	`PATCH .../archive`	`PATCH .../restore`
Workflows	`GET /workflows`	`POST /workflows`	`GET /workflows/:id`	`PATCH /workflows/:id`	`PATCH .../archive`	`PATCH .../restore`
Requirements	`GET /workflows/:id/requirements`	`POST /workflows/:id/requirements`	`GET .../requirements/:id`	`PATCH .../requirements/:id`	`PATCH .../archive`	`PATCH .../restore`
Users	`GET /users`	`POST /users`	`GET /users/:id`	`PATCH /users/:id`	`PATCH .../archive`	`PATCH .../restore`
Events	`GET /events`	—	`GET /events/:id`	—	—	—

Common patterns

Create a workflow + requirement

BASE="https://app.proofwork.today/api/v1"
AUTH="Authorization: Bearer ***"

# Create a workflow
ASGN=$(curl -s -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"name":"Night Clean"}' $BASE/workflows)
ASGN_ID=$(echo $ASGN | jq -r '.id')

# Add a requirement to the workflow
curl -s -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"name":"Restroom Check","requirement_type":"select_option","config":{"choices":["8F","6F","4F"]}}' \
  $BASE/workflows/$ASGN_ID/requirements

Filter events

curl -s -H "$AUTH" "$BASE/events?type=submission&from=2026-07-01T00:00:00Z&limit=50"

Things and thing types

Every thing belongs to exactly one thing type, an account-declared kind of thing created in the app under Things → Manage Types (/things/types) (there is no thing-type endpoint). The type carries tracked_by — quantity or state — and, for quantity-tracked types, the unit. Address a thing by its numeric id.

POST /things fields:

Field	Notes
`name`	Required.
`thing_type_id`	Required. Must be one of your account’s active types.
`code_value`	Optional; a value is generated when omitted.
`details`	Optional object.
`label_ids`	Optional array of label ids from your account.

PATCH /things/:id accepts name, details, label_ids, opening_quantity and opening_state. The thing’s type cannot be changed after creation.

curl -s -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"name":"North Gate","thing_type_id":7,"code_value":"GATE-001"}' $BASE/things

A thing response includes id, name, code_value, thing_type_id, thing_type (the type’s name), tracked_by, unit, details, labels, archived_at, created_at and updated_at. GET /things/:id and POST /things also return qr_code and verify_token.

Create a worker user

curl -s -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"name":"Naseer","phone":"0820000003","pin":"5678","role":"worker"}' $BASE/users

Response format

All endpoints return JSON. Errors follow a consistent format:

{"error": "not found"}

List endpoints return only active (non-archived) resources by default. Use archive/restore endpoints to manage lifecycle.

Full OpenAPI spec

The canonical reference is the OpenAPI 3.0.3 spec:

Live spec: GET /docs/openapi on the app
Interactive docs: Scalar UI on the app

Import the spec into Postman, use with codegen tools, or feed to your AI agent.