API documentation

This guide explains how to call SEOforGPT over HTTP. Use an API key for servers and scripts, or a login session token when calling from the browser.

Sign inAfter signing in, open the user menu (top right) and choose API Keys to create and manage keys.

Overview

Public API v1 is the HTTP surface for scripts, CI jobs, internal tools, and agents that need to list projects, run visibility workflows, fetch reports, generate content, or manage API keys.

Every request is scoped to the authenticated user and respects plan access, quota, and per-route rate limits. For server-side use, prefer an API key. For browser or app-originated calls, use a logged-in session JWT.

https://www.seoforgpt.io/api/v1

Use this when

You want a stable HTTP API for automation, background jobs, CLI tools, or agent workflows.

Success envelope

Successful responses use { data, meta }.meta.billingincludes plan and quota hints.

OpenAPI file (optional)

If you use tools that import OpenAPI (for example code generators or API clients), you can open openapi.json in a new tab. It lists the same routes as this page in JSON form. Cloud tools that must fetch the file from the public internet (for example some Custom GPT setups) should use https://www.seoforgpt.io/openapi.json. If you are new to APIs, you can skip OpenAPI and follow the sections below. This page is the main guide.

Get an API key

Sign in. Then open the user menu (top right) and choose API Keys to create a key. Keys are shown only once when you create them. You can have up to 10 keys.

Claude: For chat tools instead of raw HTTP, use the hosted MCP connector at /mcp (OAuth). That gives the assistant the same product actions as the app, not the REST shape documented here.

Other assistants: If a product supports a remote MCP URL, it is the same /mcp endpoint as in our MCP docs. Capability and setup vary by vendor. If you only have HTTP actions, wire an OpenAPI-based action instead: use the public schema https://www.seoforgpt.io/openapi.json (preview openapi.json in a new tab) with Bearer and a user API key (sgpt_…). More help: Developers, Other assistants (MCP).

Authentication

Send a bearer token in the request header. Use an API key for scripts and server-side automation. Use a JWT when calling from a signed-in browser session or when creating, listing, or deleting API keys.

Header

Authorization: Bearer <your_api_key_or_jwt>

API keys look like sgpt_... and are the right choice for CI, cron, and agents.
JWTs come from a logged-in user session and are required for /keys management.

Quickstart

If you only need one reliable flow, use this order: list projects, choose a project, run a visibility workflow, then fetch the report.

1. List projects
Start with GET /projects and choose the project you want to work with.
2. Run visibility
Use POST /analyze/project for the project's saved prompts, or POST /analyze/custom for ad-hoc prompts and brands.
3. Fetch the report
Use GET /reports/:id with the returned data.id or GET /reports/latest if you only need the most recent report for a project.

Visibility workflows

These routes run the same brand visibility workflows used inside the app. They are the core API for recurring monitoring and one-off visibility experiments.

All visibility routes consume visibility quota. Use the returned data.id with a report route. For async runs, poll until the returned status is terminal.

POST /analyze/project (recommended)

Use this when you want the project's saved prompts from SEOforGPT. Body: projectId only. Returns 202 while multi-provider jobs run, or 200 when the report is already complete.

curl --request POST \
  --url https://www.seoforgpt.io/api/v1/analyze/project \
  --header "Authorization: Bearer $SEOFORGPT_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"projectId":"<uuid>"}'

POST /analyze/custom

Use this for ad-hoc prompt sets or a brand that is different from the one saved in the app. Body: projectId, brand, prompts (strings or { prompt } objects), plus optional competitors. Max 20 prompts. Returns HTTP 200 with a report id of type visibility_analysis_api.

curl --request POST \
  --url https://www.seoforgpt.io/api/v1/analyze/custom \
  --header "Authorization: Bearer $SEOFORGPT_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"projectId":"<uuid>","brand":"YourBrand","prompts":["query 1","query 2"]}'

POST /analyze

Legacy dispatcher. Still supported, but new integrations should prefer the explicit routes above. It accepts testId, projectId + brand + prompts, projectId + brand + crawlRecordId, or just projectId.

Reports

Report routes let you fetch either the latest report for a project or a specific report by id. Visibility reports support three views: raw, summary, and full.

raw returns normalized low-level rows.
summary is the default compact report.
full returns the richer dashboard-style report with trends, sources, and gaps.

GET /reports/latest

Use this when you do not want to track a report id yourself. Query params: required projectId, optional source=main|custom, optional view=raw|summary|full, optional answer_detail=summary|full for full reports.

curl --request GET \
  --url "https://www.seoforgpt.io/api/v1/reports/latest?projectId=<uuid>&source=main&view=full&answer_detail=summary" \
  --header "Authorization: Bearer $SEOFORGPT_TOKEN"

GET /reports/:id

Fetch a specific report id. The returned data.type is visibility_analysis, visibility_analysis_api, or generated_content. Visibility reports accept the same view and answer_detail query params.

curl --request GET \
  --url "https://www.seoforgpt.io/api/v1/reports/REPORT_ID_FROM_PREVIOUS_STEP?view=full&answer_detail=summary" \
  --header "Authorization: Bearer $SEOFORGPT_TOKEN"

After 202 from /analyze/project, poll this route until data.status is terminal.

GET /reports/:id/provider-answer

Use this drill-down route to fetch one verbatim provider answer and citations after reading an agent-safe full report with answer_detail=summary.

curl --request GET \
  --url "https://www.seoforgpt.io/api/v1/reports/REPORT_ID/provider-answer?promptKey=<prompt>&provider=openai" \
  --header "Authorization: Bearer $SEOFORGPT_TOKEN"

Agent-safe helpers

These routes back the new MCP tools and return compact assistant-friendly responses. Use them when you need trend, competitor detail, client brief, or agency actions without fetching a full report.

Method

Route

Use

GET

/projects/:projectId/visibility-trends

Compact visibility score, appearance-rate, and tracked-competitor trend. Rank trend is withheld.

GET

/projects/:projectId/competitors/:competitor

Compact detail for one competitor, with threat based on mentions and visibility gaps.

GET

/projects/:projectId/client-brief

Agency brief with trend, competitor signal, cited domains, losing prompts, and three next actions.

POST

/projects/:projectId/share-links

Creates a public report link. Body accepts timeframe, expiry, presenterName, logoUrl, and summary.

GET

/client-workspaces

Lists agency client and pitch workspaces.

GET

/account-status?projectId=<uuid>

Returns plan, quota, workspace status, and feature access.

POST

/projects/:projectId/publish-to-cms

Publishes a generated article to the connected blog; update briefs are not publishable as new posts.

Content generation

Use POST /generate-content when you want SEOforGPT to create a draft from project context. For expand-vs-new decisions, call content-suggestions first and pass its routing metadata into generation. Blog requests can return data.status: processing; poll GET /reports/:id until ready.

POST /generate-content

Body: projectId, platform (blog, linkedin, thread), topic, plus optional metadata and promptType. For update briefs, include metadata.content_action=optimize_existing_url with target_url and target_title from content-suggestions.

curl --request POST \
  --url https://www.seoforgpt.io/api/v1/generate-content \
  --header "Authorization: Bearer $SEOFORGPT_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"projectId":"<uuid>","platform":"blog","topic":"How to measure AI search visibility"}'

The response includes data.id for GET /reports/:id and may include data.status: processing for blog drafts.
It also returns context_quality and context_message so you know whether the draft used completed website analysis.

Readiness & prompt helpers

These routes are useful when you want website-readiness output or prompt suggestions in automation. They are real public API routes even though they are more advanced than the main visibility/content flows.

POST /readiness

Runs the same website-readiness workflow as the app. Body: required projectId, optional forceRerun, optional url override. Response includes data.id, data.cached, and data.result.

curl --request POST \
  --url https://www.seoforgpt.io/api/v1/readiness \
  --header "Authorization: Bearer $SEOFORGPT_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"projectId":"<uuid>","forceRerun":false}'

POST /suggest-prompts

Generates prompt suggestions from an existing crawl. Body: required crawlRecordId, optional projectId, optional brand, optional competitors. Response includes prompt_count and may include a saved test id in report_url.

curl --request POST \
  --url https://www.seoforgpt.io/api/v1/suggest-prompts \
  --header "Authorization: Bearer $SEOFORGPT_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"crawlRecordId":"<uuid>","projectId":"<uuid>"}'

POST /projects/:id/content-suggestions

Generates routed content opportunities using the same content planner as the app. Topic objects include content_action, target_url, target_title, coverage_status, match_reason, and persisted. New articles and update briefs are returned in topics; covered_existing_url items are route-only skip signals returned in skipped_topics with persisted=false.

curl --request POST \
  --url https://www.seoforgpt.io/api/v1/projects/<project_id>/content-suggestions \
  --header "Authorization: Bearer $SEOFORGPT_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"count":10}'

API keys

Key-management routes require a JWT from a logged-in user session, not an API key. The actual secret key value is returned only once at creation time.

POST /keys

Create an API key. Body: optional name and optional expires_at. Returns HTTP 201 with data.key.

curl --request POST \
  --url https://www.seoforgpt.io/api/v1/keys \
  --header "Authorization: Bearer $SEOFORGPT_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"name":"CI automation","expires_at":"2027-06-01T00:00:00.000Z"}'

GET /keys

List your API keys with prefix, name, created time, last-used time, and expiry.

DELETE /keys/:id

Delete one API key owned by the authenticated user.

Errors & limits

API-owned errors return a predictable envelope. Rate-limited responses also include retry headers such as Retry-After and X-RateLimit-*.

REPORT_NOT_READY

A completed report is not available yet.

NO_ENTITLEMENT

The account or project cannot use that feature.

CMS_NOT_CONNECTED

Publishing requires an active blog connection.

UPDATE_BRIEF_NOT_PUBLISHABLE

Update briefs must be applied to the existing URL, not published as new posts.

RATE_LIMITED

Retry after the response reset time.

INTERNAL_ERROR

Retry later or contact support.

{
  "error": {
    "code": "BILLING_REQUIRED",
    "message": "content quota exceeded",
    "details": {
      "remaining": 0
    },
    "request_id": "0d2c2e3d-5f04-43e2-a8fb-f5d0b92e7ab1"
  }
}

400: Invalid input
401: Missing or invalid token
402: Billing or quota gate
404: Resource not found
409: Conflict (e.g. API key limit reached)
429: Rate limit exceeded
500: Server error