REST API

The dashboard is built on this API, so anything you can do in the app you can script. The base URL is {API_URL}/api (http://localhost:4100/api on a default self-hosted install).

Authentication

Send an OpenSEO API key as Authorization: Bearer oseo_…. Create keys under Settings; a key is shown once and acts as you, so treat it like a password. Keys can be revoked at any time and cannot create further keys. The dashboard itself uses a session cookie and may only make changes from its own origin.

Responses

Every response is JSON: { "ok": true, "data": … } on success, or { "ok": false, "error": { "code", "message", "details?" } } with a 4xx or 5xx status. Codes are listed in Errors and troubleshooting. IDs are UUIDs; a malformed one is a 404.

Lookups

POST /projects/:projectId/lookups/:name runs one paid lookup with its input as the JSON body. Inputs are validated before anything is spent; omitted market fields default to the project's.

# Price a lookup (free), then run it with a ceiling
curl -X POST "$API_URL/api/projects/$PROJECT/lookups/keyword_ideas?dryRun=1" \
  -H "Authorization: Bearer $OSEO_KEY" -H "Content-Type: application/json" \
  -d '{"keyword":"emergency plumber","limit":150}'

curl -X POST "$API_URL/api/projects/$PROJECT/lookups/keyword_ideas?maxCostUsd=0.10" \
  -H "Authorization: Bearer $OSEO_KEY" -H "Content-Type: application/json" \
  -d '{"keyword":"emergency plumber","limit":150}'

{
  "ok": true,
  "data": {
    "name": "keyword_ideas",
    "estimate": { "min": 0.03, "max": 0.08 },
    "data": { "seed": "emergency plumber", "keywords": [ ... ] },
    "costUsd": 0.08,
    "cached": false,
    "fetchedAt": "2026-10-15T09:30:00.000Z"
  }
}

cached: true results have costUsd: 0. If some parts of a multi-part lookup (the domain overview) fail, the parts that were paid for are returned with an errors list and are not cached. Names: keyword_ideas, keyword_metrics, serp, autocomplete, keyword_trends, domain_overview, domain_keywords, domain_pages, competitors_domain, competitors_serp, keyword_gap, backlinks_summary, backlinks_history, backlinks_list, backlinks_referring_domains, backlinks_anchors, backlinks_pages, link_intersect, onpage_check, lighthouse, maps_search, maps_place, maps_reviews, ai_compare. GET /lookups lists them with descriptions and cache times.

Account

Projects

GET/POST /projects, GET/PATCH/DELETE /projects/:projectId. Fields: name, domain, locationCode, locationName, country, language, context (free-form notes for agents). When locationCode comes without country, the country (and a missing name) is looked up from the code; an unknown code is refused rather than guessed. Deleting a project deletes everything in it.

Saved keywords

Rank tracking

AI visibility

Site audit

Local SEO

Search Console and Analytics

Free: these read the user's own Google data and spend nothing from YepAPI. Connecting is done in the dashboard (GET /google/:provider/connect starts Google's consent screen and needs a signed-in session, not an API key). Search Console periods end three days ago; GA4 periods end yesterday.

Free tools (public)

GET /public/tools lists the tools and markets. POST /public/tools/:tool runs one, with no account, behind the guards described in Run the free tools. These routes are meant for the site, not for scripts: use an API key and the lookups above instead.