Documentation version: 2026-10-23.6
Canonical: https://docs.creator.gg/tools/links_update.md

# links_update

Edit a published destination or metadata, toggle URL masking (link cloaking), or pause/resume a link. Cloaking requires an HTTPS destination that permits iframe embedding. Read links_get first and supply its revision. Published slugs are immutable. Reuse the same requestId when retrying an uncertain operation.

## Execution

Call this MCP tool at https://mcp.creator.gg/mcp. The connection selects the workspace. A tool name is not a REST route.

Effect: changes workspace data. requestId is required by the service (8–128 characters); reuse it only for the same action and arguments.
This action has destructive or external-delivery effects. Resolve the user's requested scope before execution.


## Example arguments

Examples illustrate the schema. Replace placeholder IDs with workspace IDs and recalculate dates. For mutations, use a new requestId for each new action and retain it for identical retries.

```json
{
  "linkId": "link_example",
  "revision": 1,
  "state": "paused",
  "requestId": "example-links_update-001"
}
```

## Input schema

Generated from the executable tool contract. The behavior notes and related guide cover rules that JSON Schema cannot express.

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "linkId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "pattern": "^[a-zA-Z0-9_-]+$"
    },
    "revision": {
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "destinationUrl": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4096
    },
    "preview": {
      "description": "Replace public preview overrides. Blank or omitted fields in this object inherit destination metadata; null restores all destination defaults. Omit preview entirely to keep current overrides.",
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "title": {
              "type": "string",
              "maxLength": 300
            },
            "description": {
              "type": "string",
              "maxLength": 1000
            },
            "imageUrl": {
              "type": "string",
              "maxLength": 2048
            }
          },
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ]
    },
    "cloaking": {
      "description": "Enable or disable link cloaking. Requires an HTTPS destination that allows iframe embedding.",
      "type": "boolean"
    },
    "tracking": {
      "type": "object",
      "properties": {
        "source": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        },
        "medium": {
          "type": "string",
          "enum": [
            "link",
            "email",
            "social",
            "paid_social",
            "cpc",
            "display",
            "referral",
            "affiliate",
            "sms",
            "video",
            "paid_video",
            "offline"
          ]
        },
        "campaign": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        },
        "content": {
          "description": "Placement or creative, for example email-hero or post-demo-a.",
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        },
        "term": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        }
      },
      "required": [
        "source",
        "medium",
        "campaign",
        "content"
      ],
      "additionalProperties": false
    },
    "title": {
      "type": "string",
      "maxLength": 200
    },
    "tags": {
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 40
      }
    },
    "expiresAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
        },
        {
          "type": "null"
        }
      ]
    },
    "state": {
      "type": "string",
      "enum": [
        "active",
        "paused"
      ]
    },
    "requestId": {
      "description": "Required by the Creator Platform service for mutations: a stable 8–128 character identifier. Reuse on retries; change for a new action.",
      "type": "string",
      "pattern": "^[A-Za-z0-9_.:-]{8,128}$"
    }
  },
  "required": [
    "linkId",
    "revision"
  ],
  "additionalProperties": false
}
```

## Result interpretation

Inspect status, message and operation-specific data; list and record shapes vary. A completed read or accepted request does not prove delivery or publication. Reconcile unknown outcomes. HUMAN_ACTION_REQUIRED returns instructions without performing the action.

## Related guides

- [short-links](https://docs.creator.gg/guides/short-links.md)
- [Recovery](https://docs.creator.gg/guides/recovery.md)