Source Endpoint

The source endpoint initialises the widget by fetching AI-generated content for a given page URL. It is the primary entry point for all widget features.

POST /source

Called automatically when a <faqsir-widget> or <faqsir-panel> element mounts on the page. The widget only calls this endpoint once per page load — subsequent elements on the same page reuse the cached response.

Request

curl -X POST https://faqsir.com/api/source \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"url": "https://example.com/article/my-article"}'

Request Body

{
  "url": "https://example.com/article/my-article"
}

Field	Type	Required	Description
url	string	Yes	The full URL of the current page. Must use http or https scheme. The API uses this to identify and generate content for the article.

Validation Rules

• The url field is required and must be a valid URL with an http or https scheme.
• Each URL must be unique per site — submitting the same URL again returns the previously generated content.
• All plans include unlimited press releases (sources). Each unique URL is processed once per site — subsequent requests return cached content.

Success Response

Status: 200 OK (existing source) or 201 Created (new source)

{
  "data": {
    "id": "9e2f1a3b-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
    "generated": {
      "faq": [
        {
          "key": "revenue-growth",
          "question": "What drove revenue growth this quarter?",
          "generic_perspective": "The company reported revenue growth driven by..."
        }
      ],
      "summary_paragraphs": [
        "The article discusses the company's latest quarterly results...",
        "Key highlights include a 15% increase in revenue..."
      ],
      "sentiment_analysis": 7.5,
      "youtube_url": "https://www.youtube.com/watch?v=example"
    },
    "meta": {
      "can_use_chat": true,
      "can_use_sentiment": true,
      "can_use_video": true
    }
  }
}

Response Fields

data

Field	Type	Description
id	string	UUID identifying this source. Used as source_id when calling the Chat and Stats endpoints.

data.generated

Field	Type	Description
faq	array	List of AI-generated FAQ objects. Always present on all plans.
summary_paragraphs	array	Ordered list of summary paragraph strings. Always present on all plans.
sentiment_analysis	number|null	Sentiment score from 1.0 (very negative) to 10.0 (very positive). Only present when the engagement intelligence feature is enabled.
youtube_url	string|null	URL of the generated video summary. Only present on Plus and Pro plans with video credits. See Video Credits.

data.generated.faq[]

Field	Type	Description
key	string	Unique identifier for this FAQ item. Used for analytics tracking.
question	string	The AI-generated question text.
generic_perspective	string	The AI-generated answer to the question.

data.meta

The meta object indicates which features are enabled for the authenticated site's subscription plan. The widget uses these flags to show or hide tabs and functionality.

Field	Type	Description
can_use_chat	boolean	Whether the chat feature is enabled. Available on Plus (Basic Chat) and Pro (Advanced AI Chat) plans.
can_use_sentiment	boolean	Whether sentiment analysis data is included. Available on Plus and Pro plans.
can_use_video	boolean	Whether the video tab should be displayed. Available on Plus and Pro plans.

Error Responses

Status	Description	Response Body
401	Invalid or missing API token	{"message": "Unauthenticated."}
402	Subscription expired or missing	{"message": "Payment required."}
422	Validation error (invalid URL)	{"message": "...", "errors": {"url": ["..."]}}
429	Rate limit exceeded	{"message": "Too Many Attempts."}

Widget Error Handling

When the widget receives a non-2xx response or an invalid response structure (missing data.generated), it displays a generic error message with a retry button:

"We were unable to load this content. Please try again."

Content Generation

When a new URL is submitted, the API queues a background job to extract and analyse the page content. The AI generates:

1. Summary paragraphs — A concise overview of the article's key points
2. FAQs — Relevant questions and answers derived from the content
3. Sentiment score — An overall tone analysis (Plus and Pro plans)
4. Video summary — An AI-narrated video summary (Plus and Pro plans, requires credits)

Processing priority depends on your plan tier — Pro sources are processed at high priority, Plus at default, and Starter at low priority.

Next Steps