Public REST API

Preferium AI Edge exposes a token-authenticated public REST API so customers can read their SEO data and trigger optimizations programmatically. The full machine- readable contract is the OpenAPI 3.1 spec served live at https://api.preferium.com/v1/openapi.json — this page is the human summary.

Base URL + authentication

Base URL: https://api.preferium.com
Auth: a per-tenant API token, sent as Authorization: Bearer <token>. Mint, scope, IP-restrict, and rotate tokens from the dashboard (Settings → API tokens). Tokens carry a scope and never expire silently — they can be revoked or rotated (with a grace window) at any time.
Scopes: public:read (the read endpoints below) and public:write (the two write endpoints). A token only carries the scopes you grant it.
Service accounts: a token’s actor_type is user or service (M2M); both are recorded in the hash-chained audit trail governed by AUDIT-CHAIN-001 in the Trust Center control table — a limited control, not an externally verified one.

Limits

Rate limit: per-token, fixed-window (default 300 requests/minute); a 429 response carries a Retry-After header. Configurable per deployment — the default is DEFAULT_API_KEY_RATE_LIMIT_PER_MIN in apps/api/src/lib/api-key-rate-limit.ts, and pnpm check:public-claims fails if this page and that constant disagree.
Plan gate: the write endpoints require a Pro or Enterprise plan.
AI-inflight cap: concurrent AI generations are capped per tenant per tier; an over-cap call returns 429 with the current/limit counts.
IP allowlist (optional): a token can be restricted to specific IPs/CIDRs.

Read endpoints (`public:read`)

The authoritative, always-current list is the OpenAPI spec: https://api.preferium.com/v1/openapi.json. This page publishes no endpoint count. It carried one — “21 read endpoints as of 2026-08-13” — and it was wrong by the time anyone read it, in the same way the hand-copied list of 9 it replaced was wrong. A repository guard (pnpm check:openapi-inventory) keeps the spec and the routes in step; the categories below point at the spec rather than restating a number that goes stale between deploys.

Area	What you can read
Domains + pages	Domains, crawled pages, per-page AI optimizations
AI visibility	LLM brand-visibility scores, citation milestones
Site audit	Site-audit issues and health
Keywords + SERP	Tracked keywords, SERP rankings
Reports + usage	Generated reports and API usage

Write endpoints (`public:write`, Pro/Enterprise)

Method + path	Effect
`POST /v1/pages/{id}/optimizations/generate`	Re-run AI optimization for a page (deducts 1 credit)
`POST /v1/pages/{id}/optimizations/deploy`	Deploy selected per-element optimizations to the edge (`title`/`description`/`h1`/`jsonld`)

MCP server

The same read/write surface is available as a Model Context Protocol server (17 tools — 16 reads + deploy_optimization; generating optimizations spends credits and stays dashboard-only behind ConfirmSpend) for AI-agent clients, authenticated with the same API tokens. Unlike the endpoint count this page deliberately does not publish, the tool count has a source a reader can open — apps/mcp/src/tool-catalog.ts — and it is pinned from both sides: apps/mcp/test/tools.test.ts asserts the catalog length and pnpm check:public-claims fails if this page drifts from it. Registry distribution (registry.modelcontextprotocol.io, name com.preferium/ai-edge) is planned post-launch.

Errors

Errors are JSON { "error": "<code>", "detail": "<message>" } with a conventional HTTP status (400 invalid input, 401 unauthenticated, 402 insufficient credits, 403 wrong scope/plan, 404 not found, 429 rate-limited). The OpenAPI spec is the authoritative per-endpoint schema.