Questions API

The questions resource is the core. Every other resource (categories, translations, revisions) hangs off it.

List

curl "https://api.thefaq.app/api/v1/acme/questions?limit=20" \
  -H "Authorization: Bearer $FAQAPP_API_KEY"

Query params: page (default 1), limit (1–100, default 25), status (published, draft, or all), search (text match on question and answer), sortBy, sortOrder (asc or desc), and view (full or summary).

Response:

{
  "data": [
    {
      "id": "q_8X3F",
      "slug": "how-to-rotate-keys",
      "question": "How do I rotate an API key?",
      "answer": "Create a new key, swap it in your env, then revoke the old one.",
      "status": "published",
      "categoryId": "c_billing",
      "publishedAt": "2026-05-12T14:23:00Z",
      "scheduledPublishAt": null,
      "createdAt": "2026-05-10T10:00:00Z",
      "updatedAt": "2026-05-12T14:23:00Z"
    }
  ],
  "meta": { "pagination": { "page": 1, "limit": 20, "total": 1, "pages": 1 } }
}

Get by id or slug

curl https://api.thefaq.app/api/v1/acme/questions/how-to-rotate-keys \
  -H "Authorization: Bearer $FAQAPP_API_KEY"

Accepts either id (q_8X3F) or slug (how-to-rotate-keys).

Create

curl -X POST https://api.thefaq.app/api/v1/acme/questions \
  -H "Authorization: Bearer $FAQAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "How do I rotate an API key?",
    "answer": "Create a new key, swap it in your env, then revoke the old one.",
    "categoryId": "c_billing",
    "status": "published"
  }'

Returns the created question with server-generated id and slug. Retrying a create makes a second question; to re-run imports safely, use POST /questions/bulk with explicit slugs, which updates rows whose slug already exists.

Required scope: write.

Update

curl -X PATCH https://api.thefaq.app/api/v1/acme/questions/q_8X3F \
  -H "Authorization: Bearer $FAQAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "answer": "Updated answer." }'

Every update creates a revision. The most recent 50 are retained per question.

Schedule publish

Set status: "draft" and scheduledPublishAt: "2026-06-01T12:00:00Z". A 5-minute cron promotes scheduled questions whose time has passed.

Delete

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

Returns 204 No Content. Soft delete; question is purged from the database after 30 days.

Reorder

Set the display order of questions in one request. Pass the ids in the order you want them — index 0 becomes order 0, index 1 becomes 1, and so on. Questions not in the list keep their current order. You can also set order directly on create or update.

curl -X POST https://api.thefaq.app/api/v1/acme/questions/reorder \
  -H "Authorization: Bearer $FAQAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ids": ["q_8X3F", "q_2Kd9", "q_Lp01"] }'

Body:

• ids (string[], required, 1–1000): question ids in the desired order. Every id must belong to this organization, or the whole request is rejected with validation_error.

Response:

{ "data": { "updated": 3 } }

Required scope: write.

Error codes

• not_found (404): id or slug doesn’t exist in this org
• validation_error (400): required field missing, wrong type, or unknown category
• plan_limit_exceeded (403): your org hit its question cap; upgrade or delete
• slug_conflict (409): manual slug already taken in this org