REST API v1: API keys, authentication and endpoints

The REST API v1 lets you do most of your panel work from code: list sites, start crawls, pull issues, open AI fixes, and manage Pixel rules, keywords and content. Keys belong to an organization, and a key only ever sees its own organization's data.

#Prerequisites

• Only the organization's owner or an admin can create and revoke keys. Other roles don't see the API keys tab.
• API access is included in the Pro and Agency plans. If your plan doesn't include it, the tab shows a notice with a See plans link.

#Creating an API key

1. Open Settings → API keys.
2. In Key name, describe where the key will be used (at least 2 characters, e.g. "CI").
3. If the key needs to start crawls or create fixes, rules, keywords or content, tick write scope. Leave it unticked for a read-only key.
4. Click Create key.
5. Copy the key that starts with sa_live_ right away with Copy key. It is never shown again; the list only keeps its Prefix.

#Authentication and base URL

• Base URL: https://seoasist.com/api/v1
• Header: Authorization: Bearer sa_live_…
• An ?api_key=sa_live_… query parameter is also accepted. Keys in URLs tend to end up in logs, so use it for testing only.

Scopes: a read key can call every GET endpoint. The write scope unlocks POST and DELETE requests. A write request with a read-only key returns 403.

curl -H "Authorization: Bearer sa_live_..." \
  https://seoasist.com/api/v1/sites

#Response envelope

Every successful JSON response looks like this:

{ "ok": true, "data": {}, "ms": 42 }

data holds the endpoint's result and ms is the request time in milliseconds. The one exception is llms.txt, which returns plain text (text/plain). Errors return { "ok": false, "error": "<code>", "message": "…" }.

#Endpoints

All paths are relative to the base URL. {id} is a site ID, which you get from GET /sites.

Content statuses: idea, planned, generating, draft, review, approved, scheduled, published, failed, archived. Pixel kind values: title, meta_description, canonical, robots, h1, img_alt, og, json_ld, hreflang, redirect, lang, attr. matchType: exact, prefix, regex, all.

#Examples

Start an AI fix:

curl -X POST https://seoasist.com/api/v1/sites/SITE_ID/fixes \
  -H "Authorization: Bearer sa_live_..." \
  -H "Content-Type: application/json" \
  -d '{"issueCode":"missing_meta_description"}'

Add keywords to tracking:

curl -X POST https://seoasist.com/api/v1/sites/SITE_ID/keywords \
  -H "Authorization: Bearer sa_live_..." \
  -H "Content-Type: application/json" \
  -d '{"keywords":["seo tool","site audit"]}'

Crawls and fixes run as queued jobs. Follow their progress through the matching GET endpoint (/sites/{id}, /sites/{id}/fixes).

#Error codes

#FAQ

#I lost my key. Can I see it again?

No. Keys are stored only as a hash. Revoke the old one and create a new key.

#Can I use the same key in an MCP client?

Yes. The MCP server view under the API keys tab shows a ready-made config for Claude Desktop, Claude Code and Cursor. Put the key in the SEOASIST_API_KEY variable; the MCP tools call the same endpoints.

#Can I call the API straight from a browser?

The API returns an Access-Control-Allow-Origin: * header. Still, never embed a key in a public page: anyone who sees it can access your organization's data.