API reference

curl https://api.thefaq.app/api/v1/health

Every endpoint sits under /api/v1/{organizationSlug}/.... Authentication is by Authorization: Bearer <api-key> on every request except /api/v1/health.

Conventions

Request: JSON for write bodies, query params for filters. Content-Type required on writes.

Response envelope:

{
  "data": { /* the actual payload */ },
  "meta": {
    "pagination": { "limit": 20, "cursor": "...", "hasMore": true }
  }
}

Error envelope:

{
  "error": {
    "code": "question_not_found",
    "message": "No question with id 'q_8X3F' in organization 'acme'. Check the id or list questions to find the right one.",
    "details": { "organization": "acme", "id": "q_8X3F" }
  }
}

Status codes: 200 OK, 201 Created, 204 No Content (deletes), 400 (validation), 401 (auth), 403 (scope), 404 (not found), 409 (conflict), 429 (rate limit), 500 (us).

Authentication

API keys are scoped (read / write / admin). Send as a bearer token:

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

Rate limits are per-key per-minute, derived from the organization’s plan tier. The response includes X-RateLimit-Remaining and X-RateLimit-Reset.

Resources

• Questions: /api/v1/{org}/questions
• Categories: /api/v1/{org}/categories
• Translations: /api/v1/{org}/questions/{id}/translations
• API keys: /api/v1/{org}/api-keys
• Plans: /api/v1/{org}/plans

Health

curl https://api.thefaq.app/api/v1/health

Returns 200 with { ok: true, orgs: <n>, ms: <n> } when the Worker + Hyperdrive + Neon path is healthy. 503 otherwise.