Migrating from v1

Your existing API key and host work with v2. If a v2 request answers 403 although the key works on v1, see Authentication. 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 below collects them. These tools have no v2 endpoints and stay on v1:

Audit: Create Audit query and Get Audit query.
SERP Analyzer: Create SERP Analyzer query and Create a batch of SERP Analyzer queries, with CSV exports of queries, prominent terms, and search results.
AI Detector: Detect AI content in a text.
Humanizer: Humanize text.
Locations: 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	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	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	`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	`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	None, so a retried create makes a second resource.	Content Editor, content template, and custom voice creates accept an `Idempotency-Key` header.
Rate limiting	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	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`	`GET /api/v2/content_editors` for the whole organization, or `GET /api/v2/workspaces/{workspace_id}/content_editors` for one workspace
`POST /api/v1/content_editors`	`POST /api/v2/workspaces/{workspace_id}/content_editors`
`GET /api/v1/content_editors/{id}`	`GET /api/v2/workspaces/{workspace_id}/content_editors/{id}`
`PATCH /api/v1/content_editors/{id}`	`PUT /api/v2/workspaces/{workspace_id}/content_editors/{content_editor_id}/content` for content, or `PATCH /api/v2/workspaces/{workspace_id}/content_editors/{content_editor_id}/seo_guidelines/terms` for included terms
`POST /api/v1/content_editors/{id}/auto_optimize`	`POST /api/v2/workspaces/{workspace_id}/content_editors/{content_editor_id}/auto_optimize`
`GET /api/v1/content_editors/{id}/content`	`GET /api/v2/workspaces/{workspace_id}/content_editors/{content_editor_id}/content`
`GET /api/v1/content_editors/{id}/content_score`	`GET /api/v2/workspaces/{workspace_id}/content_editors/{content_editor_id}/seo_guidelines/score`
`GET /api/v1/content_editors/{id}/structural_guidelines`	`GET /api/v2/workspaces/{workspace_id}/content_editors/{content_editor_id}/seo_guidelines/structure`
`GET /api/v1/content_editors/{id}/terms`	`GET /api/v2/workspaces/{workspace_id}/content_editors/{content_editor_id}/seo_guidelines/terms`
`GET /api/v1/workspaces`	`GET /api/v2/workspaces`
`POST /api/v1/serp_analyzer`	`POST /api/v1/serp_analyzers`, which stays on v1
`POST /api/v1/serp_analyzer/batches`	`POST /api/v1/serp_analyzers/batch`, which stays on v1

For a first v2 request, follow the Quickstart.

Overview

API v2

API v1 (legacy)

Migrating from v1

Status of v1

What changed

Endpoint mapping

​Status of v1

​What changed

​Endpoint mapping

Status of v1

What changed

Endpoint mapping