Intake (AI generation)

Intake takes a URL, scrapes the content, generates grounded FAQ candidates, and returns them as draft questions you can review and claim into your org. Public endpoint (no API key required), rate-limited per IP to stay free for evaluators.

The fallback chain runs OpenAI → Anthropic → Google. Typical end-to-end time is 25–35 seconds.

Start an intake job

curl -X POST https://api.thefaq.app/api/v1/intake/start \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/help" }'

Body:

• url (string, required): fully qualified http(s) URL; must be publicly fetchable
• language (string, optional, default en): BCP-47 tag for the output language
• maxQuestions (integer, optional, default 10, max 25): soft cap on how many candidates to return

Response (immediate, before AI runs):

{
  "data": {
    "id": "in_2kL9pQ",
    "status": "queued",
    "url": "https://example.com/help",
    "createdAt": "2026-05-20T10:00:00Z"
  }
}

No scope required. Intake is intentionally public so anyone can try without signing up. Per-IP rate limit: 5 starts per hour.

Poll for results

curl https://api.thefaq.app/api/v1/intake/in_2kL9pQ

Response (when complete):

{
  "data": {
    "id": "in_2kL9pQ",
    "status": "complete",
    "url": "https://example.com/help",
    "candidates": [
      {
        "question": "How do I reset my password?",
        "answer": "Open the sign-in page and click 'Forgot password'. Enter your email and we'll send a one-time link.",
        "category": "Account",
        "grounding": "Found in section 'Account recovery' of the source page."
      }
    ],
    "createdAt": "2026-05-20T10:00:00Z",
    "completedAt": "2026-05-20T10:00:28Z"
  }
}

Status values:

• queued: accepted, waiting to start
• processing: scraping or generating
• complete: candidates ready
• failed: the error field carries the reason

Claim into an organization

Once you have an account and an API key, claim a completed intake into your org as draft questions:

curl -X POST https://api.thefaq.app/api/v1/intake/in_2kL9pQ/claim \
  -H "Authorization: Bearer $FAQAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "organizationSlug": "acme", "defaultStatus": "draft" }'

Body:

• organizationSlug (string, required): target org
• defaultStatus (string, optional, default draft): draft or published
• defaultCategorySlug (string, optional): if omitted, the intake's suggested category names are matched to existing categories or created as new ones

Response: the created questions, in the same shape as Questions API.

Required scope: write. Intake jobs expire 24 hours after completion.

Error codes

• intake_not_found (404): id doesn't exist or has expired
• url_unreachable (400): scraper couldn't fetch the URL (DNS, 4xx, or robots.txt blocked)
• url_no_content (400): the page was reachable but the scraper found no extractable prose
• rate_limit_exceeded (429): per-IP burst limit exceeded; wait and try again
• all_providers_failed (502): all three AI providers errored; safe to retry

Intake hardening (start)

The anonymous start endpoint is bot-gated and budget-capped:

• turnstile_required (400): a bot-protection token is required. In production a token is always required; render the Turnstile widget and resubmit.
• turnstile_failed (400): the supplied token was rejected.
• body_too_large (413): the request body exceeded 64 KB.
• ai_intake_budget_exceeded (429): the free intake service has hit its global daily ceiling. details.resetAt is the next reset (UTC midnight). Try again later or sign up.
• intake_busy (429): too many intakes are in flight right now; transient — retry shortly.
• intake_misconfigured (503): the service is temporarily misconfigured. Retry shortly.
• intake_unavailable (503): a transient infrastructure error. The limiter fails closed, so retry shortly.

Claim

• unauthorized (401): sign in required to claim a FAQ.
• body_too_large (413): the claim body exceeded 64 KB.
• org_limit_reached (403): you already own the maximum number of organizations on the free plan. details.owned and details.limit show the counts. Upgrade or remove one to claim another.