> ## 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.

# Update Content Editor content

> Replaces the content of the Content Editor. Requires the editor to be in `completed` state.

Request body format negotiated via the `Content-Type` header:

| Content-Type Header   | Body Format |
|-----------------------|-------------|
| `text/html` (default) | HTML        |
| `text/markdown`       | Markdown    |

The request body is always treated as UTF-8, regardless of any `charset` parameter in the `Content-Type` header.

Triggers an asynchronous recalculation of the Content Score, including both the SEO and AI Search scores. Each fires its own
webhook when its score settles (`content_editor.seo_score.calculated`/`.failed` and
`content_editor.ai_search_score.calculated`/`.failed`); once both have settled the
`content_editor.content_score.recalculated` webhook fires with the unified Content Score. As a
fallback, poll each score's `status` — the SEO score on `GET .../seo_guidelines/score`, the AI
Search score on `GET .../ai_search_guidelines/score` — or read the unified `content_score` on
`GET .../content_editors/:id`.

**Content sanitization**: the body is parsed and re-serialized server-side; the stored content may differ from what was submitted. Markdown bodies go through the same pipeline (parsed, then re-serialized).

Common transformations:

| Transformation | Example |
| -- | -- |
| HTML tag re-balancing | `<p><p></p>` becomes `<p></p><p></p>` |
| Disallowed tags stripped | `<iframe>`, `<script>`, and similar are dropped |
| Disallowed attributes stripped | attributes on otherwise-allowed tags may be removed |

The response is `204 No Content` regardless of any rewrites — **callers cannot infer what was modified from the response**. Re-fetch `GET /content_editors/:id/content` to inspect the canonical stored form.

**Rate limit**: 10 requests/sec




## OpenAPI

````yaml /api/openapi-v2.json put /api/v2/workspaces/{workspace_id}/content_editors/{content_editor_id}/content
openapi: 3.0.0
info:
  description: >+
    Audit, SERP Analyzer, AI Detector, and Humanizer are not yet available in v2
    — see the v1 API docs.


    Building an LLM or agent integration?
    [/llms.txt](https://app.surferseo.com/llms.txt) is a plain-text,
    machine-readable index of this API.


    ## Authentication


    Most API requests require an `API-KEY` header with a valid API key.
    Operations that do not require authentication state that explicitly.



    ## Workspaces


    Most v2 resource endpoints are scoped to a workspace via the URL path:
    `/api/v2/workspaces/:workspace_id/...`.


    The API key must belong to an organization that owns the workspace.
    Attempting to access another organization's workspace returns `404 Not
    Found` (not `403`) to avoid leaking resource existence.



    ## Pagination


    List endpoints whose reference page documents `page` and `page_size` return
    paginated responses; the other

    list endpoints return every item with `meta.total` plus any
    endpoint-specific metadata their reference page documents. Use query
    parameters to control pagination:


    | Parameter   | Default | Max | Description                |

    |-------------|---------|-----|----------------------------|

    | `page`      | 1       | —   | Page number (1-indexed)    |

    | `page_size` | 25      | 100 | Number of items per page   |


    Response includes a `meta` object with pagination details:


    ```json

    {
      "data": [...],
      "meta": {
        "total": 156,
        "page": 1,
        "page_size": 25,
        "total_pages": 7
      }
    }

    ```



    ## Filtering


    List endpoints support filtering via bracket-notation query parameters:


    ```

    GET
    /api/v2/workspaces/123/content_editors?filter[state]=completed&filter[inserted_after]=2024-04-12T15:23:45Z

    ```


    Supported filters are documented per endpoint. Unknown filter keys are
    silently ignored. Applied filters are reflected in the response
    `meta.filters` object.



    ## Ordering


    List endpoints support ordering via `sort` and `order` query parameters:


    ```

    GET /api/v2/workspaces/123/content_editors?sort=inserted_at&order=desc

    ```


    - `sort` — field to sort by. Supported fields are documented per endpoint.
    Defaults to `inserted_at`.

    - `order` — `asc` or `desc`. Defaults to `desc`.



    ## Idempotency


    Non-idempotent operations (`POST` requests that create resources) support an
    `Idempotency-Key` header:


    ```

    POST /api/v2/workspaces/123/content_editors

    Idempotency-Key: client-generated-uuid-here

    ```


    If a request with the same key was already processed, the API answers with
    the original status code and the resource as it is now, without running the
    action again. Keys expire after 24 hours. Using the same key with a
    different request path returns `422`, a request still in progress under the
    same key returns `409`, and a failed request does not store its key, so the
    same key can retry it.



    ## Rate Limiting


    Rate limits are enforced per API key, per endpoint. When exceeded, the API
    returns `429` with a `Retry-After` header. Per-endpoint limits are
    documented on each operation.


    v2 responses additionally include `x-ratelimit-limit`,
    `x-ratelimit-remaining`, and `x-ratelimit-reset` (Unix timestamp, seconds)
    headers describing the current window state.



    ## Errors


    Newer v2 endpoints return errors in this envelope:


    ```json

    {
      "error": {
        "reason": "validation_error",
        "message": "Request validation failed",
        "details": [
          { "field": "keywords", "reason": "required" }
        ]
      }
    }

    ```


    | HTTP Status | Reason                   |
    Description                                      |

    |-------------|--------------------------|--------------------------------------------------|

    | 400         | `validation_error`       | Invalid request
    parameters                       |

    | 401         | `unauthorized`           | Missing or invalid API
    key                       |

    | 403         | `permission_denied`      | Valid key but no access,
    including plan/billing  |

    | 404         | `not_found`              | Resource does not
    exist                          |

    | 406         | `not_acceptable`         | Requested response format
    unavailable            |

    | 409         | `conflict`               | Wrong resource state or
    idempotency key in use   |

    | 413         | `content_too_large`      | Request body too
    large                           |

    | 415         | `unsupported_media_type` | Unsupported request content
    type                 |

    | 422         | `unprocessable_entity`   | Request understood but cannot be
    processed       |

    | 422         | `quota_exceeded`         | Feature enabled but credit/quota
    limit reached   |

    | 429         | `rate_limit_exceeded`    | Too many
    requests                                |

    | 500         | `internal_error`         | Unexpected server
    error                          |



    ## Webhooks


    Some asynchronous operations emit webhook events. Operations that emit
    events list the event names and payload notes in their descriptions.


    Webhook setup is organization-level. Configure an HTTPS endpoint that
    accepts POST requests and responds with a `2xx` status, then contact Surfer
    support to register the endpoint and receive a verification key.


    Surfer sends webhook requests with a `Verification-Key` header and a JSON
    body.



    ## Webhook Events


    - `content_editor.ai_article.completed`

    - `content_editor.ai_article.failed`

    - `content_editor.ai_article.waiting_for_user_input`

    - `content_editor.ai_search_score.calculated`

    - `content_editor.ai_search_score.failed`

    - `content_editor.seo_score.calculated`

    - `content_editor.seo_score.failed`

    - `content_editor.content_score.recalculated`

    - `content_editor.auto_optimize.completed`

    - `content_editor.auto_optimize.failed`

    - `content_editor.auto_optimize.cancelled`

    - `content_editor.initialization.completed`

    - `content_editor.initialization.failed`

    - `content_editor.seo_guidelines.competitors.load_more.completed`

    - `content_editor.seo_guidelines.competitors.load_more.failed`

    - `content_editor.outline.completed`

    - `content_editor.outline.failed`

  title: Surfer API
  version: v2.0
servers:
  - url: https://app.surferseo.com
    variables: {}
security: []
tags:
  - name: Workspaces
    x-displayName: Workspaces
  - description: >-
      Maintaining a legacy integration? The v1 Content Editor endpoints remain
      available.
    name: Content Editors
    x-displayName: Content Editors
  - name: AI Articles
    x-displayName: AI Articles
  - name: Auto-Optimize
    x-displayName: Auto-Optimize
  - name: SEO Guidelines
    x-displayName: SEO Guidelines
  - name: AI Search
    x-displayName: AI Search
  - name: Outline
    x-displayName: Outline
  - name: Permalinks
    x-displayName: Permalinks
  - name: Content Templates
    x-displayName: Content Templates
  - name: Custom Voices
    x-displayName: Custom Voices
  - name: Surfer Content Templates
    x-displayName: Content Template Presets
    x-group: Content Template Presets
  - description: Available in v1 only. See the v1 API docs.
    name: Audit
    x-displayName: Audit
  - description: Available in v1 only. See the v1 API docs.
    name: SERP Analyzer
    x-displayName: SERP Analyzer
  - description: Available in v1 only. See the v1 API docs.
    name: AI Detector
    x-displayName: AI Detector
  - description: Available in v1 only. See the v1 API docs.
    name: Humanizer
    x-displayName: Humanizer
paths:
  /api/v2/workspaces/{workspace_id}/content_editors/{content_editor_id}/content:
    put:
      tags:
        - Content Editors
      summary: Update Content Editor content
      description: >
        Replaces the content of the Content Editor. Requires the editor to be in
        `completed` state.


        Request body format negotiated via the `Content-Type` header:


        | Content-Type Header   | Body Format |

        |-----------------------|-------------|

        | `text/html` (default) | HTML        |

        | `text/markdown`       | Markdown    |


        The request body is always treated as UTF-8, regardless of any `charset`
        parameter in the `Content-Type` header.


        Triggers an asynchronous recalculation of the Content Score, including
        both the SEO and AI Search scores. Each fires its own

        webhook when its score settles
        (`content_editor.seo_score.calculated`/`.failed` and

        `content_editor.ai_search_score.calculated`/`.failed`); once both have
        settled the

        `content_editor.content_score.recalculated` webhook fires with the
        unified Content Score. As a

        fallback, poll each score's `status` — the SEO score on `GET
        .../seo_guidelines/score`, the AI

        Search score on `GET .../ai_search_guidelines/score` — or read the
        unified `content_score` on

        `GET .../content_editors/:id`.


        **Content sanitization**: the body is parsed and re-serialized
        server-side; the stored content may differ from what was submitted.
        Markdown bodies go through the same pipeline (parsed, then
        re-serialized).


        Common transformations:


        | Transformation | Example |

        | -- | -- |

        | HTML tag re-balancing | `<p><p></p>` becomes `<p></p><p></p>` |

        | Disallowed tags stripped | `<iframe>`, `<script>`, and similar are
        dropped |

        | Disallowed attributes stripped | attributes on otherwise-allowed tags
        may be removed |


        The response is `204 No Content` regardless of any rewrites — **callers
        cannot infer what was modified from the response**. Re-fetch `GET
        /content_editors/:id/content` to inspect the canonical stored form.


        **Rate limit**: 10 requests/sec
      operationId: KSeoWeb.Api.V2.ContentEditors.Content.Controller.update
      parameters:
        - description: ''
          in: path
          name: workspace_id
          required: true
          schema:
            $ref: '#/components/schemas/EntityId'
        - description: ''
          in: path
          name: content_editor_id
          required: true
          schema:
            $ref: '#/components/schemas/EntityId'
      requestBody:
        content:
          text/html:
            schema:
              type: string
          text/markdown:
            schema:
              type: string
        description: Raw content (HTML or Markdown)
        required: false
      responses:
        '204':
          description: >-
            Content updated. Body is sanitized and re-serialized; response does
            not echo any rewrites — re-fetch to inspect.
          headers:
            x-ratelimit-limit:
              description: >-
                Maximum number of requests allowed in the current window for
                this endpoint and API key.
              schema:
                example: 10
                type: integer
              style: simple
            x-ratelimit-remaining:
              description: >-
                Requests remaining in the current window. `0` means the next
                request will be rate-limited.
              schema:
                example: 7
                type: integer
              style: simple
            x-ratelimit-reset:
              description: Unix timestamp (seconds) at which the current window resets.
              schema:
                example: 1714838400
                type: integer
              style: simple
        '400':
          content:
            application/json:
              example:
                error:
                  details:
                    - field: keywords
                      reason: required
                  reason: validation_error
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Validation error
          headers:
            x-ratelimit-limit:
              description: >-
                Maximum number of requests allowed in the current window for
                this endpoint and API key.
              schema:
                example: 10
                type: integer
              style: simple
            x-ratelimit-remaining:
              description: >-
                Requests remaining in the current window. `0` means the next
                request will be rate-limited.
              schema:
                example: 7
                type: integer
              style: simple
            x-ratelimit-reset:
              description: Unix timestamp (seconds) at which the current window resets.
              schema:
                example: 1714838400
                type: integer
              style: simple
        '401':
          content:
            application/json:
              example:
                error:
                  details: []
                  reason: unauthorized
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
          headers:
            x-ratelimit-limit:
              description: >-
                Maximum number of requests allowed in the current window for
                this endpoint and API key.
              schema:
                example: 10
                type: integer
              style: simple
            x-ratelimit-remaining:
              description: >-
                Requests remaining in the current window. `0` means the next
                request will be rate-limited.
              schema:
                example: 7
                type: integer
              style: simple
            x-ratelimit-reset:
              description: Unix timestamp (seconds) at which the current window resets.
              schema:
                example: 1714838400
                type: integer
              style: simple
        '403':
          content:
            application/json:
              example:
                error:
                  details: []
                  reason: permission_denied
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Forbidden
          headers:
            x-ratelimit-limit:
              description: >-
                Maximum number of requests allowed in the current window for
                this endpoint and API key.
              schema:
                example: 10
                type: integer
              style: simple
            x-ratelimit-remaining:
              description: >-
                Requests remaining in the current window. `0` means the next
                request will be rate-limited.
              schema:
                example: 7
                type: integer
              style: simple
            x-ratelimit-reset:
              description: Unix timestamp (seconds) at which the current window resets.
              schema:
                example: 1714838400
                type: integer
              style: simple
        '404':
          content:
            application/json:
              example:
                error:
                  details: []
                  reason: not_found
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not found
          headers:
            x-ratelimit-limit:
              description: >-
                Maximum number of requests allowed in the current window for
                this endpoint and API key.
              schema:
                example: 10
                type: integer
              style: simple
            x-ratelimit-remaining:
              description: >-
                Requests remaining in the current window. `0` means the next
                request will be rate-limited.
              schema:
                example: 7
                type: integer
              style: simple
            x-ratelimit-reset:
              description: Unix timestamp (seconds) at which the current window resets.
              schema:
                example: 1714838400
                type: integer
              style: simple
        '406':
          content:
            application/json:
              example:
                error:
                  details:
                    - allowed:
                        - application/json
                      field: accept
                      reason: unsupported
                  message: 'Accept must be one of: application/json'
                  reason: not_acceptable
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not acceptable
          headers:
            x-ratelimit-limit:
              description: >-
                Maximum number of requests allowed in the current window for
                this endpoint and API key.
              schema:
                example: 10
                type: integer
              style: simple
            x-ratelimit-remaining:
              description: >-
                Requests remaining in the current window. `0` means the next
                request will be rate-limited.
              schema:
                example: 7
                type: integer
              style: simple
            x-ratelimit-reset:
              description: Unix timestamp (seconds) at which the current window resets.
              schema:
                example: 1714838400
                type: integer
              style: simple
        '409':
          content:
            application/json:
              example:
                error:
                  details: []
                  message: The request conflicts with the current resource state.
                  reason: conflict
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Content Editor not completed
          headers:
            x-ratelimit-limit:
              description: >-
                Maximum number of requests allowed in the current window for
                this endpoint and API key.
              schema:
                example: 10
                type: integer
              style: simple
            x-ratelimit-remaining:
              description: >-
                Requests remaining in the current window. `0` means the next
                request will be rate-limited.
              schema:
                example: 7
                type: integer
              style: simple
            x-ratelimit-reset:
              description: Unix timestamp (seconds) at which the current window resets.
              schema:
                example: 1714838400
                type: integer
              style: simple
        '413':
          content:
            application/json:
              example:
                error:
                  details: []
                  reason: content_too_large
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Content too large
          headers:
            x-ratelimit-limit:
              description: >-
                Maximum number of requests allowed in the current window for
                this endpoint and API key.
              schema:
                example: 10
                type: integer
              style: simple
            x-ratelimit-remaining:
              description: >-
                Requests remaining in the current window. `0` means the next
                request will be rate-limited.
              schema:
                example: 7
                type: integer
              style: simple
            x-ratelimit-reset:
              description: Unix timestamp (seconds) at which the current window resets.
              schema:
                example: 1714838400
                type: integer
              style: simple
        '415':
          content:
            application/json:
              example:
                error:
                  details: []
                  message: 'Set Content-Type: application/json.'
                  reason: unsupported_media_type
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unsupported media type
          headers:
            x-ratelimit-limit:
              description: >-
                Maximum number of requests allowed in the current window for
                this endpoint and API key.
              schema:
                example: 10
                type: integer
              style: simple
            x-ratelimit-remaining:
              description: >-
                Requests remaining in the current window. `0` means the next
                request will be rate-limited.
              schema:
                example: 7
                type: integer
              style: simple
            x-ratelimit-reset:
              description: Unix timestamp (seconds) at which the current window resets.
              schema:
                example: 1714838400
                type: integer
              style: simple
        '429':
          content:
            application/json:
              example:
                error:
                  details:
                    - retry_after: 30
                  reason: rate_limit_exceeded
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Rate limit exceeded
          headers:
            Retry-After:
              description: Seconds the client should wait before retrying the request.
              schema:
                example: 30
                type: integer
              style: simple
            x-ratelimit-limit:
              description: >-
                Maximum number of requests allowed in the current window for
                this endpoint and API key.
              schema:
                example: 10
                type: integer
              style: simple
            x-ratelimit-remaining:
              description: >-
                Requests remaining in the current window. `0` means the next
                request will be rate-limited.
              schema:
                example: 7
                type: integer
              style: simple
            x-ratelimit-reset:
              description: Unix timestamp (seconds) at which the current window resets.
              schema:
                example: 1714838400
                type: integer
              style: simple
        '500':
          content:
            application/json:
              example:
                error:
                  details: []
                  message: An unexpected error occurred.
                  reason: internal_error
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal error
          headers:
            x-ratelimit-limit:
              description: >-
                Maximum number of requests allowed in the current window for
                this endpoint and API key.
              schema:
                example: 10
                type: integer
              style: simple
            x-ratelimit-remaining:
              description: >-
                Requests remaining in the current window. `0` means the next
                request will be rate-limited.
              schema:
                example: 7
                type: integer
              style: simple
            x-ratelimit-reset:
              description: Unix timestamp (seconds) at which the current window resets.
              schema:
                example: 1714838400
                type: integer
              style: simple
      callbacks: {}
      security:
        - API Key: []
components:
  schemas:
    EntityId:
      example: 123
      minimum: 1
      title: EntityId
      type: integer
    ErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetails'
      required:
        - error
      title: ErrorResponse
      type: object
    ErrorDetails:
      properties:
        details:
          description: Structured details; shape depends on `reason`.
          items:
            type: object
          type: array
        message:
          description: Optional human-readable context.
          type: string
        reason:
          description: Machine-readable error key.
          type: string
      required:
        - reason
        - details
      title: ErrorDetails
      type: object
  securitySchemes:
    API Key:
      in: header
      name: API-KEY
      type: apiKey

````

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