Categories

Categories group questions. Every question belongs to exactly one category. Categories carry a slug (URL-safe identifier), a display name, an explicit order for sort, and an optional description.

List

curl https://api.thefaq.app/api/v1/acme/categories \
  -H "Authorization: Bearer $FAQAPP_API_KEY"

Query params:

• limit (1–100, default 50)
• cursor (opaque, from the previous response’s meta.pagination.cursor)
• q (text search across name + description)

Response:

{
  "data": [
    {
      "id": "cat_billing",
      "slug": "billing",
      "name": "Billing",
      "description": "Subscriptions, invoices, refunds.",
      "order": 1,
      "questionCount": 8,
      "createdAt": "2026-04-01T10:00:00Z",
      "updatedAt": "2026-05-19T14:23:00Z"
    }
  ],
  "meta": { "pagination": { "limit": 50, "cursor": null, "hasMore": false } }
}

Get by id or slug

curl https://api.thefaq.app/api/v1/acme/categories/billing \
  -H "Authorization: Bearer $FAQAPP_API_KEY"

Accepts either id (cat_billing) or slug (billing).

Create

curl -X POST https://api.thefaq.app/api/v1/acme/categories \
  -H "Authorization: Bearer $FAQAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Billing",
    "description": "Subscriptions, invoices, refunds.",
    "order": 1
  }'

Body:

• name (string, required): display name; slug auto-generated from this
• slug (string, optional): override the auto-slug
• description (string, optional): shown on the category landing in default renderers
• order (integer, optional, default 0): lower numbers sort first

Required scope: write.

Update

curl -X PATCH https://api.thefaq.app/api/v1/acme/categories/billing \
  -H "Authorization: Bearer $FAQAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "order": 2, "description": "Updated description." }'

Any field accepted by create can be patched. Slug changes do not redirect old URLs — plan ahead.

Required scope: write.

Delete

curl -X DELETE https://api.thefaq.app/api/v1/acme/categories/billing \
  -H "Authorization: Bearer $FAQAPP_API_KEY"

Returns 204 No Content. Categories with questionCount > 0 cannot be deleted — move or delete the questions first, or pass ?force=true to move them to the default category atomically.

Required scope: write.

Audit log

Every create/update/delete writes an audit entry. Retrieve recent ones:

curl https://api.thefaq.app/api/v1/acme/categories/audit \
  -H "Authorization: Bearer $FAQAPP_API_KEY"

Returns the last 100 mutations with actor (member id or API-key fingerprint), action, before/after diffs, and timestamps.

Error codes

• category_not_found (404): id or slug doesn’t exist in this org
• validation_failed (400): required field missing or wrong type
• slug_conflict (409): slug already taken in this org
• category_not_empty (409): delete attempted on category with questions — use ?force=true or move questions first
• plan_limit_reached (402): org hit its category cap