thefaqapp
Guides

CRUD Workflows

Create, read, update, and delete FAQ content via the API

This guide walks through common content management workflows using the TheFAQApp API. All examples assume you have an API key with write scope. See Authentication for setup.

Base URL: https://app.thefaq.app/api/v1/{organizationSlug}

Questions

Create a Question

curl -X POST https://app.thefaq.app/api/v1/your-org/questions \
  -H "Authorization: Bearer faq_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "How do I reset my password?",
    "answer": "<p>Click <strong>Forgot Password</strong> on the login page and follow the email instructions.</p>",
    "published": true,
    "categoryId": "clx_category_id"
  }'
const response = await fetch(
  'https://app.thefaq.app/api/v1/your-org/questions',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer faq_your-api-key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      question: 'How do I reset my password?',
      answer: '<p>Click <strong>Forgot Password</strong> on the login page and follow the email instructions.</p>',
      published: true,
      categoryId: 'clx_category_id',
    }),
  }
);

const { data } = await response.json();
console.log(data.slug); // "how-do-i-reset-my-password"

Response:

{
  "data": {
    "id": "clx...",
    "question": "How do I reset my password?",
    "answer": "<p>Click <strong>Forgot Password</strong> on the login page...</p>",
    "slug": "how-do-i-reset-my-password",
    "published": true,
    "featured": false,
    "sortOrder": 0,
    "category": { "id": "clx...", "name": "Account", "slug": "account" },
    "tags": [],
    "createdAt": "2026-02-28T10:00:00.000Z",
    "updatedAt": "2026-02-28T10:00:00.000Z"
  }
}

List Questions with Pagination

curl "https://app.thefaq.app/api/v1/your-org/questions?page=1&limit=10" \
  -H "Authorization: Bearer faq_your-api-key"
const response = await fetch(
  'https://app.thefaq.app/api/v1/your-org/questions?page=1&limit=10',
  {
    headers: { 'Authorization': 'Bearer faq_your-api-key' },
  }
);

const { data, meta } = await response.json();
console.log(`Page ${meta.pagination.page} of ${meta.pagination.pages}`);
console.log(`${meta.pagination.total} total questions`);

Response:

{
  "data": [
    { "id": "clx...", "question": "How do I reset my password?", "slug": "how-do-i-reset-my-password", "published": true }
  ],
  "meta": {
    "pagination": { "page": 1, "limit": 10, "total": 42, "pages": 5 }
  }
}

Update a Question

Use PATCH with the question slug to update specific fields.

curl -X PATCH https://app.thefaq.app/api/v1/your-org/questions/how-do-i-reset-my-password \
  -H "Authorization: Bearer faq_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "answer": "<p>Visit <a href=\"/reset\">the reset page</a> and enter your email address.</p>",
    "featured": true
  }'
const response = await fetch(
  'https://app.thefaq.app/api/v1/your-org/questions/how-do-i-reset-my-password',
  {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer faq_your-api-key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      answer: '<p>Visit <a href="/reset">the reset page</a> and enter your email address.</p>',
      featured: true,
    }),
  }
);

const { data } = await response.json();

Delete a Question

curl -X DELETE https://app.thefaq.app/api/v1/your-org/questions/how-do-i-reset-my-password \
  -H "Authorization: Bearer faq_your-api-key"
await fetch(
  'https://app.thefaq.app/api/v1/your-org/questions/how-do-i-reset-my-password',
  {
    method: 'DELETE',
    headers: { 'Authorization': 'Bearer faq_your-api-key' },
  }
);
// Returns 204 No Content on success

See Questions API Reference for full parameter details.

Categories

Create a Category

curl -X POST https://app.thefaq.app/api/v1/your-org/categories \
  -H "Authorization: Bearer faq_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Billing",
    "description": "Questions about plans, payments, and invoices"
  }'
const response = await fetch(
  'https://app.thefaq.app/api/v1/your-org/categories',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer faq_your-api-key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'Billing',
      description: 'Questions about plans, payments, and invoices',
    }),
  }
);

const { data } = await response.json();
console.log(data.slug); // "billing"

List Categories

curl "https://app.thefaq.app/api/v1/your-org/categories" \
  -H "Authorization: Bearer faq_your-api-key"
const response = await fetch(
  'https://app.thefaq.app/api/v1/your-org/categories',
  {
    headers: { 'Authorization': 'Bearer faq_your-api-key' },
  }
);

const { data } = await response.json();
// data is an array of categories with questionCount

Update and Delete

Update and delete work the same as questions -- use PATCH and DELETE with the category slug.

# Update
curl -X PATCH https://app.thefaq.app/api/v1/your-org/categories/billing \
  -H "Authorization: Bearer faq_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "description": "Updated description" }'

# Delete (fails if category has questions)
curl -X DELETE https://app.thefaq.app/api/v1/your-org/categories/billing \
  -H "Authorization: Bearer faq_your-api-key"

See Categories API Reference for full parameter details.

Organizing Content

Assign a Question to a Category

When creating or updating a question, pass the categoryId:

curl -X PATCH https://app.thefaq.app/api/v1/your-org/questions/my-question \
  -H "Authorization: Bearer faq_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "categoryId": "clx_billing_category_id" }'
await fetch(
  'https://app.thefaq.app/api/v1/your-org/questions/my-question',
  {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer faq_your-api-key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ categoryId: 'clx_billing_category_id' }),
  }
);

Reorder Questions

Update the sortOrder field on each question to control display order:

curl -X PATCH https://app.thefaq.app/api/v1/your-org/questions/first-question \
  -H "Authorization: Bearer faq_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "sortOrder": 1 }'

The GET /questions endpoint supports several query parameters for filtering:

ParameterTypeDescription
searchstringFull-text search across question and answer
categorystringFilter by category slug
statusstringpublished or draft
featuredbooleanFilter to featured questions only
tagsstringComma-separated tag filter
sortBystringcreatedAt, updatedAt, sortOrder, question
sortOrderstringasc or desc
pagenumberPage number (default: 1)
limitnumberItems per page (default: 25, max: 100)
# Search published questions in the "billing" category, sorted by newest
curl "https://app.thefaq.app/api/v1/your-org/questions?search=payment&category=billing&status=published&sortBy=createdAt&sortOrder=desc" \
  -H "Authorization: Bearer faq_your-api-key"
const params = new URLSearchParams({
  search: 'payment',
  category: 'billing',
  status: 'published',
  sortBy: 'createdAt',
  sortOrder: 'desc',
});

const response = await fetch(
  `https://app.thefaq.app/api/v1/your-org/questions?${params}`,
  {
    headers: { 'Authorization': 'Bearer faq_your-api-key' },
  }
);

const { data, meta } = await response.json();

For full-text search across all content, use the dedicated search endpoint:

curl "https://app.thefaq.app/api/v1/your-org/search?q=reset+password" \
  -H "Authorization: Bearer faq_your-api-key"

See Search API Reference for details.

Bulk Operations

The bulk endpoint lets you create, update, publish, unpublish, delete, or categorize multiple questions in a single request.

# Bulk publish multiple questions
curl -X POST https://app.thefaq.app/api/v1/your-org/questions/bulk \
  -H "Authorization: Bearer faq_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "publish",
    "ids": ["clx_id_1", "clx_id_2", "clx_id_3"]
  }'
// Bulk categorize questions
const response = await fetch(
  'https://app.thefaq.app/api/v1/your-org/questions/bulk',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer faq_your-api-key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      action: 'categorize',
      ids: ['clx_id_1', 'clx_id_2'],
      categoryId: 'clx_billing_category_id',
    }),
  }
);

const { data } = await response.json();
console.log(`${data.count} questions updated`);

Available bulk actions: publish, unpublish, delete, categorize.

Translations

If your organization has multiple languages configured, you can manage translations for each question.

Create a Translation

curl -X POST https://app.thefaq.app/api/v1/your-org/translations \
  -H "Authorization: Bearer faq_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "questionId": "clx_question_id",
    "language": "es",
    "question": "Como puedo restablecer mi contrasena?",
    "answer": "<p>Haga clic en <strong>Olvide mi contrasena</strong> en la pagina de inicio de sesion.</p>"
  }'
const response = await fetch(
  'https://app.thefaq.app/api/v1/your-org/translations',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer faq_your-api-key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      questionId: 'clx_question_id',
      language: 'es',
      question: 'Como puedo restablecer mi contrasena?',
      answer: '<p>Haga clic en <strong>Olvide mi contrasena</strong> en la pagina de inicio de sesion.</p>',
    }),
  }
);

AI-Powered Translation

Let the API translate content automatically using AI:

curl -X POST https://app.thefaq.app/api/v1/your-org/translations/ai \
  -H "Authorization: Bearer faq_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "questionId": "clx_question_id",
    "targetLanguage": "es"
  }'
const response = await fetch(
  'https://app.thefaq.app/api/v1/your-org/translations/ai',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer faq_your-api-key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      questionId: 'clx_question_id',
      targetLanguage: 'es',
    }),
  }
);

const { data } = await response.json();
// data contains the AI-generated translation

See Translations API Reference for full parameter details.

Authentication

API key management, scopes, and secure authentication patterns

Webhooks Setup

Subscribe to events, verify signatures, and handle webhook deliveries

On this page

QuestionsCreate a QuestionList Questions with PaginationUpdate a QuestionDelete a QuestionCategoriesCreate a CategoryList CategoriesUpdate and DeleteOrganizing ContentAssign a Question to a CategoryReorder QuestionsFiltering and SearchBulk OperationsTranslationsCreate a TranslationAI-Powered Translation