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 tamper-evident audit trail.

Limits

Rate limit: per-token, fixed-window (default 300 requests/minute); a 429 response carries a Retry-After header. Configurable per deployment.
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. As of 2026-08-13 it serves 21 read endpoints and 2 write endpoints — this page previously listed only 9 and understated the surface. Rather than re-copy a list that drifts, the categories below point at the spec.

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. 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.