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

# links_prepare

Shorten and track a URL for outbound marketing, with optional URL masking (link cloaking). Read links_tracking_options first and reuse its campaign names. Every link has tracking. Omitted tracking uses shared/link/always-on with an automatic placement. When a channel is known, supply its source, medium and content; use always-on when there is no named campaign. Prefer a short meaningful slug. When slug is supplied, reuse requires that exact path; otherwise an active matching owned link with the same cloaking setting is reused. Optional cloaking keeps the short URL visible for HTTPS destinations that allow iframe embedding. Use its returned shortUrl verbatim in email, social, SMS, ads or QR codes. Does not send or publish. 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.

## Behavior and limits

Omitting tracking applies automatic everyday defaults. For known distribution, supply the actual channel and placement with the relevant campaign or always-on. Returns data.link with shortUrl, tracking, ID and revision. Reuses an active owned identical tracked destination regardless of title/tags; supplied metadata applies only on new creation. Named campaign labels are workspace-owned and capped at 500 plus the reserved always-on campaign; reuse an existing name. Published tracking labels are immutable. Always verify returned current state on receipt replay. Does not send or publish. Read guides/tracked-links.

## 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
{
  "slug": "launch-hero",
  "destinationUrl": "https://example.com/offer",
  "tracking": {
    "source": "newsletter",
    "medium": "email",
    "campaign": "2026-11-product-launch",
    "content": "email-hero"
  },
  "requestId": "example-links_prepare-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": {
    "destinationUrl": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4096
    },
    "preview": {
      "description": "Optional public preview title, description and HTTPS OG image overrides. Omitted or blank fields inherit destination metadata. Null clears all overrides. Separate from the internal link title.",
      "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": "Keep the short URL in the address bar by embedding the HTTPS destination. The destination must allow iframe embedding. Defaults to false.",
      "type": "boolean"
    },
    "tracking": {
      "description": "Always generated automatically when omitted. Supply only to override the shared/link/always-on defaults for a known channel and placement.",
      "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
    },
    "slug": {
      "description": "Prefer a short, meaningful path based on the destination or purpose, such as book-demo or meet/alex. Nested paths are supported; an optional leading slash is removed. Use 3-64 characters total, with lowercase letters, digits and hyphens per segment. Supply it whenever a readable choice is possible; avoid random-only slugs.",
      "type": "string",
      "maxLength": 65,
      "pattern": "^\\/?[a-z0-9]+(?:-[a-z0-9]+)*(?:\\/[a-z0-9]+(?:-[a-z0-9]+)*)*$"
    },
    "title": {
      "default": "",
      "type": "string",
      "maxLength": 200
    },
    "tags": {
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 40
      }
    },
    "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": [
    "destinationUrl"
  ],
  "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

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