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

# links_create

Shorten a URL: create an always-tracked shortlink with optional URL masking (link cloaking) in this Platform workspace. A destination is enough for a quick calendar or everyday link: shared/link/always-on and placement are generated automatically. Supply a short meaningful slug whenever possible, instead of accepting a random path. Do not ask for a campaign name. For a known marketing channel, use links_prepare to reuse a channel-specific tracked variant. Optional cloaking keeps the short URL visible for HTTPS destinations that allow iframe embedding. This does not send or publish a message. 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

Every created link is tracked automatically. A destination alone is enough for a calendar or everyday link: shared/link/always-on and calendar or shared-link placement. Tracking arguments customize known channel context; omission never disables tracking. No campaign question is required.

## 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": "spring-offer",
  "destinationUrl": "https://example.com/offer",
  "tracking": {
    "source": "instagram",
    "medium": "social",
    "campaign": "2026-11-product-launch",
    "content": "bio"
  },
  "title": "Spring offer",
  "tags": [
    "campaign"
  ],
  "requestId": "example-links_create-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
      }
    },
    "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"
        }
      ]
    },
    "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

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