ai_article__generate
ChatGPTStart AI Article generation for a completed 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. The job runs asynchronously and returns the article in generating_outline state. Poll ai_article__get for the state. When writing completes, the article replaces the Content Editor's document content. Enterprise and some older plans consume an AI Article credit per successful request; other plans include AI Articles in the Content Editor. Emits progress notifications when the client requests them.
ai_article__get
ChatGPTGet 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_outline
ChatGPTGet 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__list
ChatGPTList 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__submit_outline
ChatGPTSubmit 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_search_guidelines__get
ChatGPTGet the AI Search (AIO) guidelines status for a Content Editor: the AI Search score (0–100 or null), the status, facts_count, and what the score is made of. facts_coverage reports the share of facts the content covers and lists which ones. introduction reports whether the introduction satisfies each of its four aspects. The facts themselves are returned by ai_search_guidelines__list_facts. facts_count populates only when status is completed. Returns an error while the editor is scheduled, executing, or failed. This is the AI Search counterpart to seo_guidelines__get.
ai_search_guidelines__list_facts
ChatGPTList 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_tracker__get
ChatGPTGet 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_mention_gap
ChatGPTGet the mention gap for an AI Tracker project. Each count is a number of different source URLs that the project's AI answers cite in the window. base_brand.total counts the sources that mention the tracked brand. For each competitor, total counts the sources that mention that competitor. shared_total counts the sources that mention both the competitor and the tracked brand. total minus shared_total gives the sources that cite the competitor but not the tracked brand. The competitors are sorted by shared_total, highest first. Ties sort by brand_name in alphabetical order. 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. If you omit competitors, the tool uses the project's top 3 competitors by mention count. A requested competitor that the answers never mention gets a row with total 0 and shared_total 0. Brand names that contain commas are not supported.
ai_tracker__get_summary
ChatGPTGet 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_time_series
ChatGPTGet 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__list
ChatGPTList 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_brands
ChatGPTList 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_prompts
ChatGPTList 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_sources
ChatGPTList 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.
auto_optimize__get
ChatGPTGet 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__run
ChatGPTStart 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.
brand__get
ChatGPTGet 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__update
ChatGPTUpdate 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. Only provided fields change. url and gathering_data_status are never writable.
content__get
ChatGPTGet 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__update
ChatGPTReplace the entire Content Editor document body with content, interpreted as format (markdown default, or html). Available only when the editor's state is completed. The body is sanitized and re-serialized server-side, so re-fetch with content__get to read the stored form. Triggers an asynchronous Content Score recalculation; pair with content_score__get for edit-and-rescore loops.
content_editor__create
ChatGPTCreate a Content Editor for a main_keyword. Generation is asynchronous. With progress notifications the call blocks until the editor is completed or failed, or returns the latest pending state once the wait cap elapses; without them it returns immediately in scheduled state, its SERP-derived fields settle later, and you poll content_editor__get for the outcome. Each successful request consumes one Content Editor credit. With import_content_url the editor skips outline generation and its outline stays null; a keyword-only editor gets one, but its outline.status can still be scheduled when the editor reaches completed, so check it via content_editor__get before reading the outline. When neither surfer_template nor custom_template_id is set, analysis may preselect one — the workspace default template if set, otherwise a choice inferred from the SERP — or leave the editor with none.
content_editor__get
ChatGPTGet 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__list
ChatGPTList 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__update
ChatGPTUpdate a Content Editor in completed state. Only provided fields change. custom_template_id: null is rejected unless surfer_template is set, since an editor cannot return to having no template.
content_score__get
ChatGPTGet 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_template__create
ChatGPTCreate a content template in a workspace. reference_text is the reusable reference content. Set default: true to make it the workspace default. Returns the created template.
content_template__delete
ChatGPTDelete a workspace content template by id, permanently removing the template and its reference_text. Deleting a template still referenced by an editor succeeds and leaves that editor's custom_template_id dangling, so content_template__get on it returns not_found.
content_template__get
ChatGPTGet 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__list
ChatGPTList 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__update
ChatGPTUpdate a workspace content template by id. Only provided fields change. Setting default: true makes it the workspace default.
custom_voice__create
ChatGPTCreate a custom voice in a workspace. reference_text is the writing sample its style is learned from. Set default: true to make it the workspace default. Returns the created voice.
custom_voice__delete
ChatGPTDelete a workspace custom voice by id, permanently removing the voice and its reference_text.
custom_voice__get
ChatGPTGet 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__list
ChatGPTList 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__update
ChatGPTUpdate a workspace custom voice by id. Only provided fields change. Setting default: true makes it the workspace default.
gsc__query
ChatGPTQuery clicks, impressions, CTR, and position using an active workspace's saved GSC connection. Results are always current. Each call returns one page in Google's own order: clicks descending (arbitrary ties), or date ascending when grouped by date. Ranking by impressions, CTR, or position requires the complete result set: page with offset until meta.next_offset is null, then sort the rows yourself. When a property is too large to page through, narrow it with filters or a shorter date range rather than ranking a partial set. Google may omit rows. Limited to 60 requests/minute per organization; shared Google quotas may delay GSC refreshes. No retries or partial results on failure; follow quota-error guidance.
outline__get
ChatGPTGet 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__regenerate
ChatGPTRegenerate 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.
permalink__list
ChatGPTList 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.
recommendation__list
ChatGPTList 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__optimize
ChatGPTOpen 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.
seo_guidelines__get
ChatGPTGet 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_terms_coverage
ChatGPTHow 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__load_more_competitors
ChatGPTSchedule 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__update_competitors
ChatGPTSet 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_structure
ChatGPTUpdate 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_terms
ChatGPTSet 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_topics_and_questions
ChatGPTToggle 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.
skill__get
ChatGPTGet one skill playbook: the full step-by-step instructions for that workflow, as markdown. The response is the document text itself.
skill__list
ChatGPTList 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.
surfer_content_template__list
ChatGPTList 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.
workspace__activate
ChatGPTActivate a workspace that has reached ready_for_activation state, moving it to active. Required before content tools can use the workspace. The acting user must be an organization owner or admin with an active subscription.
workspace__create
ChatGPTCreate a branded workspace from a brand website URL. A workspace is a brand or site you manage in Surfer, with its own Search Console property, type, location, and state. Creation starts asynchronous setup: it also creates the workspace's brand and runs an LLM brand-knowledge analysis on url, silently skipped for plans without the brand_knowledge entitlement. All current organization owners/admins become members of the new workspace, not just the caller. The acting user must be an organization owner or admin with an active subscription. The response returns the workspace in processing state; poll workspace__get for the outcome. Setup ends in ready_for_activation (call workspace__activate to make it active) or failed. Emits progress notifications when the client requests them.
workspace__get
ChatGPTGet one workspace by id, in any state — unlike other tools, which require an active workspace. This is the poll target for workspace__create.
workspace__list
ChatGPTList 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 pages exist.
ai_article__generate
Claudeai_article__get
Claudeai_article__get_outline
Claudeai_article__list
Claudeai_article__submit_outline
Claudeai_search_guidelines__get
Claudeai_search_guidelines__list_facts
Claudeai_tracker__get
Claudeai_tracker__get_mention_gap
Claudeai_tracker__get_summary
Claudeai_tracker__get_time_series
Claudeai_tracker__list
Claudeai_tracker__list_brands
Claudeai_tracker__list_prompts
Claudeai_tracker__list_sources
Claudeauto_optimize__get
Claudeauto_optimize__run
Claudebrand__get
Claudebrand__update
Claudecontent__get
Claudecontent__update
Claudecontent_editor__create
Claudecontent_editor__get
Claudecontent_editor__list
Claudecontent_editor__update
Claudecontent_score__get
Claudecontent_template__create
Claudecontent_template__delete
Claudecontent_template__get
Claudecontent_template__list
Claudecontent_template__update
Claudecustom_voice__create
Claudecustom_voice__delete
Claudecustom_voice__get
Claudecustom_voice__list
Claudecustom_voice__update
Claudeoutline__get
Claudeoutline__regenerate
Claudepermalink__list
Clauderecommendation__list
Clauderecommendation__optimize
Claudeseo_guidelines__get
Claudeseo_guidelines__get_terms_coverage
Claudeseo_guidelines__load_more_competitors
Claudeseo_guidelines__update_competitors
Claudeseo_guidelines__update_structure
Claudeseo_guidelines__update_terms
Claudeseo_guidelines__update_topics_and_questions
Claudeskill__get
Claudeskill__list
Claudesurfer_content_template__list
Claudeworkspace__activate
Claudeworkspace__create
Claudeworkspace__get
Claudeworkspace__list
Claude
