Surfer

Get one AI Tracker project by id. An AI Tracker project tracks how AI models mention your brand and competitors across prompts and topics — how often and in what position each brand appears, what your mention gap is, which sources get cited. The models are: ai_mode, ai_overviews, openai, perplexity, and gemini. Reports refresh one time each day. The refreshed_at field shows when the last refresh ran. The disabled_at field is null while the project is active. A project with disabled_at set is no longer refreshed. The response also contains latest_run_status, the report status for each model in model_statuses, and the report day in model_statuses_date. These three fields are null until the first report completes.

ai_tracker__get

Get the AI visibility metrics for an AI Tracker project. The response contains one row for each AI model family, plus one all row that combines all model families. Each row contains mention_rate, average_position, and presence_score. mention_rate is the percentage of AI answers that mention the brand, from 0 to 100. average_position is the average rank of the brand in those answers, where rank 1 is first. presence_score is a visibility index from 0 to 100. The range parameter sets the date window: 7d, 30d, or 90d. The default is 7d. The window ends on the last day that has a complete report. A metric is null when no report covers the window.

ai_tracker__get_summary

Get the daily AI visibility metrics for one AI model family of an AI Tracker project. Each day contains mention_rate, average_position, and presence_score. The days are sorted from oldest to newest. Days without reports are not included, so the series can contain fewer days than the window. mention_rate is the percentage of AI answers that mention the brand, from 0 to 100. average_position is the average rank of the brand in those answers, where rank 1 is first. presence_score is a visibility index from 0 to 100. The range parameter sets the date window: 7d, 30d, or 90d. The default is 7d. The window ends on the last day that has a complete report. The model parameter defaults to all, which combines all model families.

ai_tracker__get_time_series

Get one AI Article by id. An AI Article is a full draft Surfer generates for a `completed` Content Editor, inheriting its template, voice, custom instructions, and target word count. Its `state` runs `new` → `generating_outline` → `writing` → `completed`, or `failed`. With `manual_outline`, it pauses at `waiting_for_user_input` for outline review before writing.

ai_article__get

Get the outline of a Content Editor's active AI Article as Markdown. Available once the article has an outline: in `waiting_for_user_input`, `writing`, `completed`, or `failed` state. Errors while the article is `new` or `generating_outline`. The response is the outline text itself.

ai_article__get_outline

Get the current state of an Auto-Optimize job. An Auto-Optimize job edits the title, headings, and section bodies of a completed Content Editor to cover missing terms and facts, raising both the SEO and AI Search scores. Every change is applied to the document immediately, with no separate review step. A `completed` job reports a `result` of `optimized` (changes applied) or `nothing_to_optimize` (no changes needed).

auto_optimize__get

Get the SEO Guidelines brief for a Content Editor: the `score`, `status`, and `structure` targets (word count, heading/paragraph/image/character counts), the SERP `competitors` with their `included` flag, the recommended `terms`, and the `topics_and_questions`. The main keyword is the first term. The SEO Content Score counts a term by presence; a term's `serp_usage` is how often the ranking competitors use it, scaled to this draft — a suggestion, not a goal, and no input to the score. `terms_scope` `included` (default) returns the included terms; `all` returns every extracted term. `terms_total` is the term count before scoping. Available only when the editor's guidelines `status` is `completed`.

seo_guidelines__get

How many times each recommended term occurs in a `completed` Content Editor's current text, for the working set of terms: the main keyword plus the terms marked included. `used_count` counts occurrences anywhere in the document and `in_headings_count` is the subset inside headings. `serp_usage` is how often the ranking competitors use the term, scaled to this draft's word count. `null` when the term has none. Read `used_count` against it: 0 means absent, below `min` means under-used, above `max` means over-used. Link text does not count toward either number and image alt text does, matching what the Content Editor shows a writer — this is a different measurement from the SEO Content Score, so a term can read as unused here and still score. `heading` marks a term recommended for a heading. Use `seo_guidelines__get` with `terms_scope` `all` to see the terms outside the working set.

seo_guidelines__get_terms_coverage

Get a workspace's brand knowledge. Brand knowledge is a workspace's brand profile: `name`, the brand's site `url`, and free-form markdown `knowledge` gathered by workspace setup. Brand is a singleton — one per workspace, with no brand id. `gathering_data_status` (`scheduled`, `completed`, or `failed`) says whether knowledge gathering finished. Returns 404 if the workspace has no brand.

brand__get

Get one Content Editor by id within a workspace. A Content Editor is a document built from SERP analysis of a `main_keyword` plus optional `secondary_keywords`. It reports its content score, generation `state`, and the status of its AI article, outline, SEO guidelines, and AI Search guidelines. The detail adds the editable fields a list item omits: `custom_instructions`, `notes`, `meta_title`, and `meta_description`.

content_editor__get

Get the Content Editor document body. `format` selects the representation returned: `markdown` (default) or `html`. Available only when the editor's `state` is `completed`. The response is the document text itself.

content__get

Get a Content Editor's content score: `seo`, `ai_search`, and the unified `total`, each with a `score` (0–100 or `null`) and a `status`. A `calculating` status means a recalculation is running; the subscores also carry `calculated_at`. For the guidelines behind the SEO score, use `seo_guidelines__get`.

content_score__get

Get one of a workspace's content templates by id. A content template is reusable reference content a Content Editor can be created from; its id goes in `custom_template_id`. The detail adds the `reference_text` body that a list item omits.

content_template__get

Get one of a workspace's custom voices by id. A custom voice is a saved writing style AI generation can apply; its id goes in `custom_voice_id`. The detail adds the `reference_text` body that a list item omits.

custom_voice__get

Get the SERP-derived structural outline of a Content Editor as Markdown headings. Returns a conflict error while the editor is not `completed`, or `not_found` when the outline row is missing. On a `completed` editor the response is empty only while the outline is pending or after it has failed; poll `outline.status` on `content_editor__get` to tell which.

outline__get

Get one skill playbook: the full step-by-step instructions for that workflow, as markdown. The response is the document text itself.

skill__get

Get one workspace by id, in any state — unlike other tools, which require an `active` workspace. This is the poll target for `workspace__create`.

workspace__get

List the AI Search (AIO) facts for a Content Editor: items gathered from the SERP and the major AI engines (Google AI Overviews and AI Mode, Gemini, OpenAI, Perplexity) for the editor's main keyword and location. Each fact carries `sources`, each with its `url` and a `cited_by` list of where the URL was found (`serp`, `ai_mode`, `ai_overviews`, `gemini`, `openai`, `perplexity`). `meta.status` reflects the analysis lifecycle; `data` is empty until `status` is `completed`. `ai_search_guidelines__get` returns the AI Search `score` and its breakdown without the facts.

ai_search_guidelines__list_facts

List the brands that the AI answers mention for the project's prompts. The list is sorted by presence_score, highest first. The list contains only brands that the answers mention in the window. This includes the tracked brand only when the answers mention it. Each row contains presence_score, average_position, and mention_rate. mention_rate is the percentage of AI answers that mention the brand, from 0 to 100. average_position is the average rank of the brand in those answers, where rank 1 is first. presence_score is a visibility index from 0 to 100. The range parameter sets the date window: 7d, 30d, or 90d. The default is 7d. The window ends on the last day that has a complete report. The model parameter defaults to all. The server sorts the rows and returns one page. The page starts at offset (default 0) and contains a maximum of limit rows (default 20, maximum 100). The meta.total field holds the full row count.

ai_tracker__list_brands

List the workspace's AI Tracker projects. An AI Tracker project tracks how AI models mention your brand and competitors across prompts and topics — how often and in what position each brand appears, what your mention gap is, which sources get cited. The models are: ai_mode, ai_overviews, openai, perplexity, and gemini. Reports refresh one time each day. The refreshed_at field shows when the last refresh ran. The disabled_at field is null while the project is active. A project with disabled_at set is no longer refreshed. Each entry contains the brand, the locale, the prompt count, refreshed_at, and disabled_at.

ai_tracker__list

List the tracked prompts of an AI Tracker project, grouped by topic. Each prompt contains mention_rate, average_position, presence_score, and its top brands. Each prompt lists a maximum of 5 brands. mention_rate is the percentage of AI answers that mention the brand, from 0 to 100. average_position is the average rank of the brand in those answers, where rank 1 is first. presence_score is a visibility index from 0 to 100. The range parameter sets the date window: 7d, 30d, or 90d. The default is 7d. The window ends on the last day that has a complete report. The model parameter defaults to all. meta.total is the number of topics.

ai_tracker__list_prompts

List the sources that the AI answers cite for an AI Tracker project. The list is sorted by references_count, highest first. With group_by domain, the default, each row is one domain with urls_count and combined mention_counts. The domain is an origin with a scheme, for example https://www.reddit.com. With group_by url, each row is one URL with a mentioned flag. The range parameter sets the date window: 7d, 30d, or 90d. The default is 7d. The window ends on the last day that has a complete report. The model parameter defaults to all. The server sorts the rows and returns one page. The page starts at offset (default 0) and contains a maximum of limit rows (default 20, maximum 100). The meta.total field holds the full row count.

ai_tracker__list_sources

List the AI Articles of a Content Editor. An AI Article is a full draft Surfer generates for a `completed` Content Editor, inheriting its template, voice, custom instructions, and target word count. Its `state` runs `new` → `generating_outline` → `writing` → `completed`, or `failed`. With `manual_outline`, it pauses at `waiting_for_user_input` for outline review before writing.

ai_article__list

List Surfer's built-in content template presets, such as blog post, listicle, or product description. A preset is read-only reference content a Content Editor can be created from. Its id goes in `surfer_template`. For the workspace's own templates, use `content_template__list`.

surfer_content_template__list

List Content Editors. A Content Editor is a document built from SERP analysis of a `main_keyword` plus optional `secondary_keywords`. It reports its content score, generation `state`, and the status of its AI article, outline, SEO guidelines, and AI Search guidelines. Results cover at most 90 days. Without date filters, that is the last 90 days. List items are summaries; `content_editor__get` returns the full detail (sub-resource statuses, permalinks, error, and editable fields).

content_editor__list

List a workspace's own content templates. A content template is reusable reference content a Content Editor can be created from. Its id goes in `custom_template_id`. At most one template is the workspace `default`; a workspace can have none, and deleting the default does not promote another. For Surfer's built-in presets, use `surfer_content_template__list`.

content_template__list

List a workspace's custom voices. A custom voice is a saved writing style AI generation can apply. Its id goes in `custom_voice_id`. At most one voice is the workspace `default`; a workspace can have none, and deleting the default does not promote another.

custom_voice__list

List a Content Editor's shareable permalinks. A permalink is a `hash`, a `type` (`edit` grants editing, `comment` grants commenting), and the shareable `url`. Available only when the Content Editor is `completed`.

permalink__list

List a workspace's recommendations. Recommendations are a workspace's suggested next SEO actions, read live from the same sources the product UI shows. `optimize` items are Content Audit pages worth re-optimizing, carrying `page_url`, `keyword`, and `current_position`/`previous_position`. `write` items are topical-map content ideas worth writing, carrying `main_keyword`, `search_volume`, and `avg_difficulty` (the raw stored value; the UI shows it divided by 100). Items already being worked on stay listed — `content_editor_id` marks that coverage on both types, while `optimization_status` and `content_score` are optimize-only; `content_score` is the linked Content Editor draft's score and is null until optimization starts. `reasons` carries insight-type codes on legacy write items and is null otherwise. To act on an optimize item, open its Content Editor: use `content_editor_id` when set, or call `recommendation__optimize` when `optimization_status` is `not_started` — that opens the page's own editor, keeping Content Audit progress tracking connected. To act on a write item, call `content_editor__create` with its `main_keyword` and `location`. `score` orders items within a type but is not comparable across types. `meta.content_audit_configured` and `meta.topical_maps_configured` say whether each source exists. The product's Mentions recommendations (AI Tracker) are not included yet. Optionally filter to one type with `type`, sort with `sort` / `order` (`sort=score` requires `type`; `inserted_at` for newest or oldest first; by default `optimize` items come before `write` items, each block score-descending), and cap items per type with `limit` (default 25; raise it to fetch deeper). Paginated with `page` and `page_size`; `meta.total` counts all items matching the filter and limit.

recommendation__list

List the skills this server ships. A skill is a markdown playbook for one multi-step Surfer workflow — acting on a workspace's recommendations, writing an article, optimizing existing content, building an outline or a content brief, or managing content templates — written to be executed with this server's tools. Each entry carries the skill name and a description of when it applies.

skill__list

List the workspaces the signed-in user belongs to. Workspaces in their organization that they are not a member of are not listed and cannot be reached. A workspace is a brand or site you manage in Surfer, with its own Search Console property, type, location, and state. Only `active` workspaces can be operated on. Results are paginated; `meta.total_pages` tells whether further `page`s exist.

workspace__list

Schedule loading of additional SERP competitors for a `completed` Content Editor. Available only when the brief's `can_load_more_competitors` is `true`. Runs asynchronously and returns immediately with `state` `executing`; poll `seo_guidelines__get` and wait for `load_more_status` to return to `idle` for the new competitors.

seo_guidelines__load_more_competitors

Open the Content Editor for an `optimize` recommendation — the same action as the product UI's Optimize button. The editor stays connected to Content Audit, so the page's optimization progress tracks in the product. Charges one Content Editor credit unless the page's editor was already paid for. Returns the refreshed optimize item with `content_editor_id` set; edit it with the content tools. Items whose editor is already open fail with a conflict; pages whose editor is still being prepared fail with a retryable error.

recommendation__optimize

Regenerate the outline of a `completed` Content Editor from the SERP competitors, applying the editor's template, custom instructions, and brand knowledge. Runs asynchronously and returns the `executing` state; `outline.status` on `content_editor__get` reports completion, then `outline__get` returns the new outline. Returns a conflict when a regeneration is already in progress.

outline__regenerate

Start an Auto-Optimize job for a `completed` Content Editor. An Auto-Optimize job edits the title, headings, and section bodies of a completed Content Editor to cover missing terms and facts, raising both the SEO and AI Search scores. Every change is applied to the document immediately, with no separate review step. A `completed` job reports a `result` of `optimized` (changes applied) or `nothing_to_optimize` (no changes needed). The job runs asynchronously and is returned in `executing` state. Poll `auto_optimize__get` for the outcome. Each run counts toward your plan's Auto-Optimize allowance. Emits progress notifications when the client requests them.

auto_optimize__run

Submit an edited outline as Markdown for a Content Editor's active AI Article and resume generation. Valid only while the article is `waiting_for_user_input`. Writing then continues asynchronously to `completed`, and the finished article replaces the Content Editor's document content. Poll `ai_article__get` for the state. Emits progress notifications when the client requests them.

ai_article__submit_outline

Set `included` on SEO Guidelines competitors of a `completed` Content Editor and recalculate the guidelines from the new selection. Competitors are matched by `url`; each `url` must be unique and at least one is required. Returns the updated competitors list.

seo_guidelines__update_competitors

Update the user-controllable structural guidelines of a `completed` Content Editor. Sets, or with `null` clears, the `word_count` override, and selects the `guidelines_baseline` scoring anchor (`word_count` or `character_count`). Each entry in `guidelines` sets or clears the `value_override` for one factor (`character_count`, `headings_count`, `paragraph_count`, `img_count`); competitor-derived `avg`/`max`/`min` are read-only and factors omitted from the list are left untouched. At least one of `guidelines_baseline`, `word_count`, or `guidelines` must be present. Returns the updated structure.

seo_guidelines__update_structure

Set `included` and `heading` on SEO Guidelines terms of a `completed` Content Editor. `included` keeps a term in the editor's working set; `heading` marks it for a heading — excluding a term clears its heading, and a heading is always included. These flags do not affect the SEO Content Score. Terms not already prominent or custom are created as custom terms (max 500); the main keyword cannot be updated. Returns the terms named in the request; `meta.total` is the editor's total term count.

seo_guidelines__update_terms

Toggle `included` on SEO Guidelines topics and questions of a `completed` Content Editor. An unknown `item` with `included: true` is created as a custom topic; with `included: false` it is ignored. Total topics is capped at 500. Returns the topics named in the request; `meta.total` is the editor's total topic count.

seo_guidelines__update_topics_and_questions