Ask a PageFox site one grounded question

What this endpoint is

/api/sites/{websiteId}/ask answers a single question about one website using only the content that website has indexed in PageFox. It is stateless: no conversation, no history, no visitor record. It exists so an agent, a crawler, or an AI search assistant running anywhere can query a site directly, which is why it takes no API key and performs no origin check.

It answers from indexed site content only. When retrieval finds nothing usable the endpoint returns an honest "this is not covered" answer rather than inventing one, and it never reads private workspace data such as leads, companies, or conversations. For those, use the REST API.

The request

One GET, one query parameter. websiteId is the website's UUID, which an owner can read from GET /api/v1/websites or copy from the dashboard.

curl --fail-with-body \
  --get \
  --data-urlencode "q=Which plan includes API access?" \
  "https://pagefox.co/api/sites/00000000-0000-4000-8000-000000000000/ask"

The response

An answer body has four fields. answer is prose. sources lists up to 4 cited pages as { url, title }. schema_org is the same answer as a schema.org Question you can embed directly. disclosure states that the answer came from an AI assistant.

{
  "answer": "The Business plan includes read-only REST API access.",
  "sources": [
    {
      "url": "https://example.com/pricing",
      "title": "Pricing"
    },
    {
      "url": "https://example.com/docs/api",
      "title": "Api"
    }
  ],
  "schema_org": {
    "@context": "https://schema.org",
    "@type": "Question",
    "name": "Which plan includes API access?",
    "url": "https://example.com",
    "acceptedAnswer": {
      "@type": "Answer",
      "text": "The Business plan includes read-only REST API access.",
      "url": "https://example.com"
    },
    "citation": [
      {
        "@type": "WebPage",
        "url": "https://example.com/pricing",
        "name": "Pricing"
      },
      {
        "@type": "WebPage",
        "url": "https://example.com/docs/api",
        "name": "Api"
      }
    ]
  },
  "disclosure": "You are interacting with an AI assistant."
}

The X-PageFox-Answer-Mode header distinguishes a real answer (grounded) from the honest fallback (no_context_fallback). Both are 200 with an empty or populated sources array, so branch on the header rather than on the status code. Responses are never cached, so a site owner turning the feature off takes effect immediately.

Error bodies are a different shape

Do not assume answer exists. A 400, 404 or 429 returns an error envelope — an error string plus disclosure, and nothing else. Check the status code first, and only then read answer.

{
  "error": "Not found",
  "disclosure": "You are interacting with an AI assistant."
}

The 503 has two forms, so branch on the presence of answer rather than on the status alone: when both models fail, you receive the four-field answer body carrying a safe unavailable message and an empty sources array; when the request fails before that point, you receive the error envelope with an extra message field.

{
  "error": "assistant_unavailable",
  "message": "This assistant is temporarily unavailable. Please try again in a moment.",
  "disclosure": "You are interacting with an AI assistant."
}

The one guarantee that does hold across every shape: disclosure is present on every response this endpoint returns, success or error, because the route builds all of them through one constructor.

When a site will answer

All of the following must hold, or the endpoint returns 404:

• The site owner has switched Agent answers on for that website. It is off by default.
• The organization is on Growth or above.
• The website is not paused, and the organization is active.

Every one of those conditions — including a website ID that simply does not exist — returns the identical 404 body. That is deliberate: the endpoint is not an oracle for which sites use PageFox or which plan they are on.

Rate limits

• 500 requests per website per day. This is the site's whole budget across all callers, and it resets daily in UTC.
• 20 requests per minute per IP, so one caller cannot spend a site's day alone.

Exhausting either returns 429 with a Retry-After header. These budgets are separate from the site's chat conversation limits and from the REST API budget.

Status codes

200

A grounded answer, or an honest "no indexed content covers this" fallback. Both carry `disclosure`; check the answer-mode header to tell them apart.

400

Error envelope. `q` is missing, empty after trimming, or longer than 500 characters.

404

Error envelope. The website does not exist, is paused, has agent answers switched off, is on a plan without the entitlement, or its organization is disabled. All five look identical on purpose.

429

Error envelope. A rate-limit bucket is exhausted. Wait for `Retry-After`.

503

Two shapes. Both models failing returns the four-field answer body with a safe unavailable message and no sources; a failure before generation returns the error envelope plus a `message` field. Retry later; nothing was fabricated either way.

The companion file

A site with agent answers enabled also serves /api/sites/{websiteId}/llms.txt, generated live from that site's indexed pages under the same opt-in and plan gate. Use it to discover what a site can answer about before you ask.

What is not available yet

There is no POST form, no streaming, no multi-turn context, no per-question caching, and no way to reach private workspace data through this endpoint. PageFox does not currently publish an SDK, an MCP server, or a general agent connection.