REST API

A scoped, versioned HTTP API over the Lokrix AI GEO engine. Every route is mounted under a real v1/ controller (NestJS + OpenAPI 3.1), takes an API-key bearer token, and returns compressed, predictable envelopes with provenance and confidence intervals.

The Lokrix AI REST API surface (/v1)A versioned root, slash v1, connects to eight endpoint groups: scans, projects, recommendations, simulate, competitors, history, reports and usage, each with an example request path./v1versionedScansPOST /v1/scansProjectsGET /v1/projectsRecommendationsGET …/recommendationsSimulatePOST /v1/simulateCompetitorsGET …/competitorsHistoryGET …/historyReportsPOST /v1/reportsUsageGET /v1/usage

Base URL & your first call

The base URL is https://api.lokrix.de with a /v1 prefix on every route. Mint a least-privilege scoped key in Settings → API keys, then send a bearer-authenticated request:

curl -H "Authorization: Bearer $LOKRIX_API_KEY" \
  https://api.lokrix.de/v1/projects

Conventions

  • Pagination — offset pagination via limit + offset; list responses return { items, total, limit, offset }.
  • Compression — send accept-encoding: gzip, br; payloads are compressed over the wire.
  • Provenance & CI — every scored payload carries a provenance badge (live / cached / predicted) and a 95% confidence interval. See Data honesty.
  • Approval gate — gated workspaces receive a 202 pending_approval envelope until an admin approves the action.
  • Rate & budget — over-limit requests return 429; over-budget live runs are rejected against the tenant credit balance.

The resource groups

The surface is grouped by resource. Project-scoped resources take a :projectId so a call always targets a single property. Each endpoint requires a matching scope.

  • Projects — The property resource. Each project scopes its own prompts, scans, and scores.
  • Scans & analyze — Start measurement — a one-shot /v1/analyze grade or a full /v1/scans run, then poll status.
  • Scores & engines — Calibrated presence probabilities with CIs, per-engine breakdowns, and citation provenance.
  • Prompts — The prompt universe — generate, activate, and lock per-project prompt sets and templates.
  • Recommendations & optimize — Prioritised, simulated moves with predicted uplift. Predictive runs cost 0 credits.
  • Competitors & analytics — Share-of-voice, head-to-head comparison, movers, anomalies, and history.
  • Alerts & notifications — Regression/anomaly alerts, digests, and notification channels.
  • Billing & usage — Credit balance, usage metering, quota, invoices.
  • Keys, webhooks & audit — Mint scoped keys, register webhooks, read the tamper-evident audit log.

The full method · path · purpose · scope tables live on the public developer reference.

OpenAPI spec

The API is described by an OpenAPI 3.1 document. When docs are published, the raw JSON is served at /openapi.json (alias /v1/openapi.json) with Swagger UI at /docs. Point any OpenAPI generator at the JSON to produce a typed client in your language — or use the maintained TypeScript SDK, which is generated from that spec.

Which calls spend credits

Only live engine runs (POST /v1/scans and POST /v1/analyze against real engines) meter credits. Reads, predictive scoring, and what-if simulation cost 0 credits. See Credits & cost.