Categories

Endpoints to list, create, and delete categories in Paperarchive. Categories are user-owned and assigned to spaces via the category_spaces model.

GET https://api.paperarchive.io/v1/categories

Scope:categories:read

List categories you own that are linked to any accessible space (legacy categories.space_id or rows in category_spaces). Each item includes membership_space_ids for all linked spaces.

Code examples

curl -X GET "https://api.paperarchive.io/v1/categories" \
  -H "Authorization: Bearer pa_live_abc123def456"

POST https://api.paperarchive.io/v1/categories

Scope:categories:write

Create a category and assign it to a space. If space_id is omitted, your default space is used (when it exists).

Request body

Name	Type	Required	Description
`name`	string	required	Category name.
`space_id`	uuid	optional	Target space for the first membership. Omit to use your default space.
`color`	string	optional	Hex color code (e.g. "#ef4444").
`icon`	string	optional	Icon name.

Code examples

curl -X POST "https://api.paperarchive.io/v1/categories" \
  -H "Authorization: Bearer pa_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{"name": "Receipts", "space_id": "space-uuid-1", "color": "#f59e0b"}'

DELETE https://api.paperarchive.io/v1/categories/:id

Scope:categories:write

Delete a category you own when it is linked to at least one space your key can access (category_spaces or legacy space_id).

Path parameters

Name	Type	Required	Description
`id`	uuid	required	The category ID to delete.

Code examples

curl -X DELETE "https://api.paperarchive.io/v1/categories/cat-uuid-1" \
  -H "Authorization: Bearer pa_live_abc123def456"

Smoke test checklist (categories API)

Use a test API key with categories:read and categories:write (and spaces:read so you can resolve space UUIDs). Run against staging or local API.

GET /v1/categories - Expect 200, success: true, array data. Each item has membership_space_ids (array, possibly empty for legacy rows before backfill).
POST with explicit space_id - POST /v1/categories with body {"name":"API Smoke Cat","space_id":"<uuid>"}. Expect 201, returned membership_space_ids contains that space.
POST without space_id - Same with only {"name":"API Smoke Cat Default"}. Expect 201 if a default space exists, or 400 with a clear error if not.
GET again - New category appears; membership_space_ids matches the space you used (or default).
DELETE - DELETE /v1/categories/<id> with the new id. Expect 200 and success: true. Repeat GET to confirm it is gone.
Restricted API key - With a key limited to one space, repeat POST targeting a space outside the key: expect 403.