> ## Documentation Index
> Fetch the complete documentation index at: https://devs.surferseo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrating from v1

> See what changed between v1 and v2 and which endpoint replaces each v1 call.

Your existing API key and host work with v2. If a v2 request answers `403` although the key works on v1, see [Authentication](/api/authentication#when-authentication-fails). Use the tables below to update workspace selection, response handling, and endpoint paths.

## Status of v1

v1 stays available, and no shutdown date is announced. Twelve v1 operations are marked deprecated: the nine Content Editor operations, the workspace list, and the two singular SERP Analyzer paths. Each deprecated reference page opens with the operation to call instead, and the [endpoint mapping](#endpoint-mapping) below collects them.

These tools have no v2 endpoints and stay on v1:

* Audit: [Create Audit query](/api/v1/audit/create-audit-query) and [Get Audit query](/api/v1/audit/get-audit-query).
* SERP Analyzer: [Create SERP Analyzer query](/api/v1/serp-analyzer/create-serp-analyzer-query-post-create) and [Create a batch of SERP Analyzer queries](/api/v1/serp-analyzer/create-a-batch-of-serp-analyzer-queries-post-create-batch), with CSV exports of [queries](/api/v1/serp-analyzer/list-serp-analyzer-queries-for-a-workspace), [prominent terms](/api/v1/serp-analyzer/get-prominent-terms), and [search results](/api/v1/serp-analyzer/get-search-results).
* AI Detector: [Detect AI content in a text](/api/v1/other/detect-ai-content-in-a-text).
* Humanizer: [Humanize text](/api/v1/other/humanize-text).
* Locations: [List supported locations](/api/v1/other/list-supported-locations), the location values other endpoints accept; it needs no API key.

## What changed

Update workspace selection and response handling when you switch endpoint paths.

| Convention | v1 | v2 |
| - | - | - |
| [Workspace selection](/api/requests#workspaces-in-the-path) | An optional `Workspace-Id` header selects the workspace, and without it v1 uses the oldest active workspace of your organization. | The workspace id moves into the URL path, with no fallback. |
| [Errors](/api/errors) | Most failures answer with a plain-text body, a few tools with a small JSON `error` object, and invalid parameters with `422` and JSON:API error objects. | Every handled failure answers with one JSON envelope, and `error.reason` names the cause. |
| [Lists](/api/requests#lists) | `from` and `to` select a creation window of at most 90 days. | `filter[inserted_after]` and `filter[inserted_before]` replace them over the same 90-day window, and sorting and state filters are new. |
| [Content update](/api/requests#document-endpoints) | `PATCH /api/v1/content_editors/{id}` takes a JSON body with `content` and `included_terms`. | `PUT .../content` takes the document itself as HTML or Markdown, and included terms move to `PATCH .../seo_guidelines/terms`. |
| [Idempotency](/api/requests#idempotent-creates) | None, so a retried create makes a second resource. | Content Editor, content template, and custom voice creates accept an `Idempotency-Key` header. |
| [Rate limiting](/api/rate-limits) | A `429` answers with the plain-text body `Rate limit exceeded. Try again in N ms` and no headers. | Under the same limits, a `429` answers with the error envelope and a `Retry-After` header, and responses gain rate-limit headers. |
| [Webhooks](/api/async-and-webhooks) | Support registers one HTTPS endpoint per organization, and events arrive with a `Verification-Key` header. | Registration, the header, and the v1 events are unchanged, and v2 adds events for scores, outlines, and competitor loading. |

## Endpoint mapping

Each deprecated v1 operation links its reference page and the operation to call instead.

| v1 operation | Replacement |
| - | - |
| [`GET /api/v1/content_editors`](/api/v1/content-editors/list-content-editors-for-a-workspace) | [`GET /api/v2/content_editors`](/api/v2/content-editors/list-all-content-editors) for the whole organization, or [`GET /api/v2/workspaces/{workspace_id}/content_editors`](/api/v2/content-editors/list-content-editors-in-workspace) for one workspace |
| [`POST /api/v1/content_editors`](/api/v1/content-editors/create-content-editor-query) | [`POST /api/v2/workspaces/{workspace_id}/content_editors`](/api/v2/content-editors/create-content-editor) |
| [`GET /api/v1/content_editors/{id}`](/api/v1/content-editors/get-content-editor-query) | [`GET /api/v2/workspaces/{workspace_id}/content_editors/{id}`](/api/v2/content-editors/get-content-editor) |
| [`PATCH /api/v1/content_editors/{id}`](/api/v1/content-editors/update-content-editor-query) | [`PUT /api/v2/workspaces/{workspace_id}/content_editors/{content_editor_id}/content`](/api/v2/content-editors/update-content-editor-content) for content, or [`PATCH /api/v2/workspaces/{workspace_id}/content_editors/{content_editor_id}/seo_guidelines/terms`](/api/v2/seo-guidelines/update-seo-guidelines-terms) for included terms |
| [`POST /api/v1/content_editors/{id}/auto_optimize`](/api/v1/content-editors/auto-optimize-content-editor-query) | [`POST /api/v2/workspaces/{workspace_id}/content_editors/{content_editor_id}/auto_optimize`](/api/v2/auto-optimize/start-auto-optimize) |
| [`GET /api/v1/content_editors/{id}/content`](/api/v1/content-editors/get-content-inside-the-content-editor) | [`GET /api/v2/workspaces/{workspace_id}/content_editors/{content_editor_id}/content`](/api/v2/content-editors/get-content-editor-content) |
| [`GET /api/v1/content_editors/{id}/content_score`](/api/v1/content-editors/get-content-score-for-the-content-editor) | [`GET /api/v2/workspaces/{workspace_id}/content_editors/{content_editor_id}/seo_guidelines/score`](/api/v2/seo-guidelines/get-seo-guidelines-score) |
| [`GET /api/v1/content_editors/{id}/structural_guidelines`](/api/v1/content-editors/get-structural-guidelines-for-the-content-editor) | [`GET /api/v2/workspaces/{workspace_id}/content_editors/{content_editor_id}/seo_guidelines/structure`](/api/v2/seo-guidelines/get-seo-guidelines-structure) |
| [`GET /api/v1/content_editors/{id}/terms`](/api/v1/content-editors/get-all-terms-for-the-content-editor) | [`GET /api/v2/workspaces/{workspace_id}/content_editors/{content_editor_id}/seo_guidelines/terms`](/api/v2/seo-guidelines/list-seo-guidelines-terms) |
| [`GET /api/v1/workspaces`](/api/v1/other/list-workspaces) | [`GET /api/v2/workspaces`](/api/v2/workspaces/list-workspaces) |
| [`POST /api/v1/serp_analyzer`](/api/v1/serp-analyzer/create-serp-analyzer-query-post-create-deprecated) | [`POST /api/v1/serp_analyzers`](/api/v1/serp-analyzer/create-serp-analyzer-query-post-create), which stays on v1 |
| [`POST /api/v1/serp_analyzer/batches`](/api/v1/serp-analyzer/create-a-batch-of-serp-analyzer-queries-post-create-batch-deprecated) | [`POST /api/v1/serp_analyzers/batch`](/api/v1/serp-analyzer/create-a-batch-of-serp-analyzer-queries-post-create-batch), which stays on v1 |

For a first v2 request, follow the [Quickstart](/api/quickstart).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.