---
title: "Update a guide"
method: PUT
path: "/api/v1/guide"
tags: ["v1", "Guide"]
---

# Update a guide

`PUT /api/v1/guide`

## Request

- Base URL: `https://app.serpmantics.com` (the document declares no server; this is the origin it was published from)
- URL: `https://app.serpmantics.com/api/v1/guide`
- Auth: HTTP bearer

Updates editable fields of a specific guide (group, status, share state, linked URL, meta, hidden expressions). Only owners may update.

## Query parameters

- `id` string, required

## Request body

- object
  - `group` string: Group/folder the guide belongs to (triggers cannibalisation analysis on previous and new group)
  - `status` '' | 'draft' | 'active' | 'review' | 'published' | 'archived': Editorial status of the guide. Empty string clears the status.
  - `shareState` 'private' | 'shared-read' | 'shared-edit': Sharing mode. Any value outside the enum is rejected with 400 (the check is case-sensitive). Plan must allow shared-read or shared-edit, otherwise 403 is returned.
  - `linkedUrl` string, uri: Public URL where the guide content is published (validated as URL)
  - `meta` object: SEO meta override for the guide
    - `title` string
    - `description` string
  - `hiddenExpressions` string[]: Expressions to hide from the optimisation suggestions

## Response `200`

Guide successfully updated. When shareState was part of the update, data.shareState echoes the state that was requested, validated and persisted by this call.

- object
  - `success` boolean
  - `data` object: Only present when shareState was part of the update
    - `shareState` 'private' | 'shared-read' | 'shared-edit': Share state requested, validated against your plan, and persisted by this call. Read it back with GET /api/v1/guide to observe the stored state.

## Other responses

- `400`: Missing guide ID, invalid status, shareState outside the enum, invalid URL, invalid meta or invalid hiddenExpressions format
- `401`: Unauthorized - User doesn't own the guide or invalid token
- `403`: Plan does not allow the requested shareState (response includes inviteToUpgrade flag)
- `410`: Guide expired. Guides are locked 180 days after their creation, because the Google results they are built on are no longer representative. The body is `{ success: false, error: "Guide expired", expiresAt: "<ISO 8601 expiry date>" }`. Definitive: do not retry, create a new guide on the same keyword. DELETE /api/v1/guide still removes an expired guide. Housekeeping is still allowed on an expired guide: a request whose body contains ONLY `group`, `status` and/or `shareState` (and, for `shareState`, only the value `private`) is accepted and applied. Anything else is refused in full, including a body that mixes an allowed field with a forbidden one: in that case nothing at all is written.
- `500`: Server error - Failed to update guide

---

[API](https://skmtc.dev/serpmantics/apis/api-serpmantics.md) · [All operations](https://skmtc.dev/serpmantics/apis/api-serpmantics/llms.txt) · [OpenAPI document](https://skmtc.dev/serpmantics/apis/api-serpmantics/revisions/885ab1bdaa96?raw)