PageFox API

Overview

The PageFox API gives your own scripts, integrations, or an AI agent programmatic read access to the same data your dashboard shows — leads, identified companies, visitor sessions, and AI conversations — scoped to your organization. It is available on the Business plan. Create a key from Settings → API keys.

The full machine-readable contract is published at /api/v1/openapi.json (OpenAPI 3.0, no authentication required to read the spec itself).

Authentication

Every request needs an Authorization header carrying a key you created in the dashboard:

Authorization: Bearer pfx_...

Keys are shown in full exactly once, at creation time. PageFox only ever stores a hash of the key — if you lose it, revoke it and create a new one. A revoked key stops working within 60 seconds. There is no CORS support — the API is designed for server-to-server or agent callers, not direct browser fetches.

Scopes

Each key is issued with one or more scopes. A request without the scope its endpoint requires gets a 403.

• leads:read — read /v1/leads
• companies:read — read /v1/companies
• sessions:read — read /v1/sessions
• conversations:read — read /v1/conversations and /v1/conversations/{id}
• websites:read, websites:write, config:write, mcp:connect — reserved for upcoming PageFox API surfaces; granting them today is inert.

Endpoints

GET /v1/leads

The unified leads feed — identified companies first, then anonymous visitor rows. Query params: page, website_id (optional). Page size is fixed at 50. Locked companies past your plan's company-metering limit render with identity fields redacted (name shows as "Locked company"), exactly as the dashboard shows them.

GET /v1/companies

The identified-company subset of the same feed. Query params: page, website_id (optional).

GET /v1/sessions

Visitor sessions. Query params: page, per_page (default 20, max 50), website_id (optional). This endpoint never returns network/IP-derived context, and only returns acquisition fields (source, referrer, utm_params) for rows whose company is not locked by company metering.

GET /v1/conversations

AI conversation summaries (no messages — use the detail endpoint for those). Query params: page, per_page (default 20, max 50), website_id (optional).

GET /v1/conversations/{id}

One conversation with its full message history. A conversation that does not exist and one that belongs to a different organization return the identical 404 response.

Pagination

Every list response is shaped:

{ "data": [...], "pagination": { "page": 1, "per_page": 20, "total": 42, "total_pages": 3 } }

Rate limits

Each key is limited per-minute; the exact limit and remaining budget are returned on every response as X-RateLimit-Remaining and X-RateLimit-Reset headers. Exceeding it returns 429.

Errors

Every error response uses the same envelope:

{ "error": { "code": "unauthorized", "message": "Invalid or revoked API key." } }

• 400 invalid_request — a query parameter failed validation.
• 401 unauthorized — missing, unknown, or revoked key, or the organization is disabled.
• 403 insufficient_scope — the key does not have the scope this endpoint requires.
• 404 not_found — resource missing, including a resource that belongs to another organization.
• 429 rate_limited — slow down.