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`)

Method + path	Returns
`GET /v1/domains`	The tenant’s domains
`GET /v1/domains/{hostname}/pages`	Pages crawled for a domain
`GET /v1/domains/{hostname}/milestones`	LLM-citation milestones for a domain
`GET /v1/pages/{id}`	A single page
`GET /v1/pages/{id}/optimizations`	A page’s per-element AI optimizations
`GET /v1/llm-visibility/{hostname}`	LLM brand-visibility scores (Phase 13)
`GET /v1/audit/{hostname}`	Site-audit issues
`GET /v1/keywords`	Tracked keywords + SERP data
`GET /v1/serp`	SERP rankings

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 (10 tools — 8 reads + optimize_page + deploy_optimization) 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.