Skip to main content
You need a plan that includes API access and an API key issued to your organization; Authentication covers who can get one and how to send it. Requests go over HTTPS to https://app.surferseo.com, under /api/v2 for the current version or /api/v1 for the legacy one; Requests and responses covers the conventions v2 endpoints share. A workspace is a brand or site you manage in Surfer; every Content Editor belongs to one, and so do the content templates and custom voices you create. A Content Editor holds, for one keyword, the guidelines derived from its search results, your content, and the scores that grade it. Surfer MCP connects AI assistants to Surfer with no API key; it signs in with your Surfer account (Surfer MCP). Zapier, Make, and Looker Studio connect through this API; the app lists them under MCP & API → API.

​
What the API covers

Everything below is available in v2.
  • Workspaces: list the workspaces your key reaches, and the Content Editors across all of them.
  • Content Editors: create one for a keyword and location, then list, read, customize, or delete it, and read or reset its share links.
  • SEO Guidelines: the competitors ranking for the keyword, and the terms, the topics and questions, and the structure drawn from their pages. Read them, adjust them, and read the SEO score.
  • AI Search guidelines: the facts gathered from the search results and the major AI engines for the keyword, with their sources. Read them and the AI Search score.
  • Content: read the content in a Content Editor or replace it. A replacement recalculates the Content Score, the combined SEO and AI Search score of the content.
  • Outline: read the outline generated from the search results, and retry it when generation failed.
  • AI Articles: generate an article in a Content Editor, review and submit its outline, and read the result.
  • Auto-Optimize: run an optimization pass whose changes apply straight to the Content Editor’s content.
  • Content templates and custom voices: create, read, update, and delete the ones in a workspace.
  • Content template presets: browse Surfer’s built-in templates, read-only and outside any workspace; reference one when creating a Content Editor.
Audit, SERP Analyzer, AI Detector, and Humanizer are available in v1 only; Migrating from v1 covers what changed between the versions.

​
What the API does not cover

Keyword Research, Topical Map, Internal Linking, Content Audit, and Rank Tracker have no endpoints; use them in the app. AI Tracker has no public endpoints; its Looker Studio connector is the supported way to export its data. The v1 Audit endpoint audits one page for one keyword, not a whole site.

​
Next steps

Follow the Quickstart to create and score your first Content Editor.

Quickstart

Your first integration end to end: a workspace, a Content Editor, its guidelines, content, and score.

Authentication

Who can get a key, how to request it, and how to send it with every request.

API v2 reference

Every endpoint with its parameters, responses, and errors.

Async operations and webhooks

How long-running jobs report progress, by polling or by webhook.

Migrating from v1

What changed in v2, and what stays in v1.
If a request fails, start with Troubleshooting. For questions these pages do not answer, contact [email protected].