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_limited (429): per-IP limit exceeded; wait and try again
• all_providers_failed (502): all three AI providers errored; safe to retry
• not_owner (403): claim attempted on an intake from a different IP (anti-stealing)