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

# Reset Content Editor permalinks

> Generates new permalink hashes for a Content Editor. Previous permalinks stop working.
When `type` is provided, only the matching permalink is reset. When omitted, all permalinks
are reset.

Requires the editor to be in `completed` state.

Returns the updated list of permalinks.

**Rate limit**: 10 requests/sec




## OpenAPI

````yaml /api/openapi-v2.json post /api/v2/workspaces/{workspace_id}/content_editors/{content_editor_id}/permalinks/reset
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}/permalinks/reset:
    post:
      tags:
        - Permalinks
      summary: Reset Content Editor permalinks
      description: >
        Generates new permalink hashes for a Content Editor. Previous permalinks
        stop working.

        When `type` is provided, only the matching permalink is reset. When
        omitted, all permalinks

        are reset.


        Requires the editor to be in `completed` state.


        Returns the updated list of permalinks.


        **Rate limit**: 10 requests/sec
      operationId: KSeoWeb.Api.V2.ContentEditors.Permalinks.Controller.reset
      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:
          application/json:
            schema:
              $ref: '#/components/schemas/ResetPermalinksParams'
        description: Reset params (optional)
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListPermalinksResponse'
          description: Updated list of permalinks
          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
        '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
        '422':
          content:
            application/json:
              example:
                error:
                  details: []
                  message: The request was understood but could not be processed.
                  reason: unprocessable_entity
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Reset failed
          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
      callbacks: {}
      security:
        - API Key: []
components:
  schemas:
    EntityId:
      example: 123
      minimum: 1
      title: EntityId
      type: integer
    ResetPermalinksParams:
      additionalProperties: false
      properties:
        type:
          description: Permalink type to reset. If omitted, resets all permalinks.
          enum:
            - edit
            - comment
          example: edit
          type: string
      title: ResetPermalinksParams
      type: object
    ListPermalinksResponse:
      properties:
        data:
          items:
            $ref: '#/components/schemas/Permalink'
          type: array
        meta:
          $ref: '#/components/schemas/TotalMeta'
      required:
        - data
        - meta
      title: ListPermalinksResponse
      type: object
    ErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetails'
      required:
        - error
      title: ErrorResponse
      type: object
    Permalink:
      properties:
        hash:
          example: abc123xyz
          type: string
        type:
          enum:
            - edit
            - comment
          example: edit
          type: string
        url:
          example: https://app.surferseo.com/drafts/s/abc123xyz
          format: uri
          type: string
      required:
        - type
        - hash
        - url
      title: Permalink
      type: object
    TotalMeta:
      properties:
        total:
          example: 8
          type: integer
      required:
        - total
      title: TotalMeta
      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.