Documentation version: 2026-10-23.6
Canonical: https://docs.creator.gg/guides/short-links.md

# Short links

Short links are included for enabled Platform workspaces. Start with workspace_status and its links module. Free preparation-only connections cannot create or manage links. The connection determines the workspace; never supply account IDs or credentials.

## Create and share

Use links_create with a public HTTP(S) destinationUrl, optional title, tags, custom slug and future expiresAt. For every outbound marketing URL, use links_tracking_options then links_prepare instead. Read guides/tracked-links for the shared campaign, source, medium and placement standard. Prefer a short, meaningful slug when creating or preparing a link. An omitted slug generates a random eight-character path as a fallback. Custom paths have 3–64 characters total and support nested segments, such as meet/alex. Each segment uses lowercase letters, digits and hyphens. An optional leading slash is removed on creation; the returned shortUrl is canonical. Paths are globally unique on s.creator.gg and are never reassigned.

Retain the returned link ID, shortUrl and revision. Creating a link makes that redirect active; it does not authorize sending email or publishing social content. Use existing channel tools only within the user's authorized scope. The dashboard at https://agents.creator.gg/?view=links also provides QR downloads, a UTM builder and filtered CSV export.

## Short, readable paths

Prefer short, meaningful slugs based on the destination or purpose, such as book-demo or launch-guide. Pass slug to links_create or links_prepare whenever a readable choice is possible. Reuse an existing suitable path; if taken, try a concise meaningful variant, using a short random suffix only when needed. Published paths cannot be renamed. Read guides/short-links for collision and retry handling.

Use one or two useful words from the public destination, page title or purpose. Keep lowercase letters, digits and hyphens in each segment, within 3–64 characters total including separating slashes. Preserve an explicitly requested nested path such as /meet/alex instead of flattening it to meet-alex. Empty segments, trailing slashes, dots, encoded characters and reserved first segments such as health or api are invalid. Paths use exact matching: meet and meet/alex may coexist and point to different destinations. Nesting adds no folder ownership, wildcard matching or redirect inheritance. Avoid filler, long copied URL paths, private customer data and random-only strings. Choose the path yourself from known context; do not make a quick request wait for a slug or campaign question. Preserve an explicitly supplied valid path.

links_prepare accepts slug as well as destination and tracking. With a slug, it reuses only an active owned link with that exact path, tracked destination and cloaking mode; a requested readable path is not replaced by an existing random path. Without a slug, matching-destination reuse remains available. Read the returned shortUrl rather than constructing one or claiming an unavailable path was reserved.

On slug_unavailable, the global path is already reserved, possibly by another business or an archived link. Never change another link or reclaim a retired path. Choose a concise meaningful qualifier, such as book-demo-call, before considering a short random suffix. Do not loop indefinitely. A different slug is a different operation and needs a fresh requestId. For an uncertain result, reconcile or retry the same arguments with the original requestId first.

Existing published paths are immutable. This preference does not rename, archive or replace existing links automatically. If the user explicitly asks for the original/direct URL, return it without creating a short link.

## Link previews and custom metadata

Masked and redirect links inherit the destination's public HTML title, description and Open Graph image by default. OG tags take priority, with Twitter and ordinary HTML title/description as fallbacks. Ordinary visitors to redirect links still get the tracked 302 redirect; recognized sharing crawlers get a 200 HTML preview. Masked pages include the same metadata above their iframe, without adding overlay controls.

Use links_preview with destinationUrl to inspect inherited metadata without creating a link. available:false means no metadata could be read, including pages without metadata, blocked reads and timeouts. No scripts are executed. JavaScript-only metadata may be unavailable. Missing titles fall back to the saved internal link name, then the destination hostname; missing descriptions and images remain empty. Failed metadata reads never disable a valid link.

Set preview:{title,description,imageUrl} in links_create, links_prepare or links_update to override any of these fields. imageUrl must be a stable, public HTTPS image URL. The top-level title is the management label and missing-destination-title fallback, separate from the public preview override. Blank or omitted fields inside preview inherit the destination field. Updating preview replaces the override object; preview:null restores all destination defaults. Omit preview entirely on update to preserve current overrides. Read links_get and supply its revision as for any other edit. Preparation reuses only a link with matching preview overrides, as well as destination, path and cloaking mode.

The Links editor has a Link preview section with inherited placeholders, an example card, individual overrides and Use destination defaults. Upload custom images through your existing media workflow and use their stable public URL. Suggested OG dimensions are 1200 by 630 pixels. Do not use temporary agent asset-preview URLs as permanent images. Destination metadata may be cached for up to 15 minutes where the destination permits caching; each short-link request still checks current state and overrides. Sharing services can retain their own older previews after an edit. Public short pages remain noindex while allowing crawlers to read their metadata. Paused, expired, archived or suspended links never serve an active preview.

## Link cloaking

Set cloaking:true in links_create, links_prepare or links_update to keep the short URL in the address bar and show the saved destination in a full-page iframe. The Links editor has the same Link cloaking checkbox. Existing and new links redirect by default; cloaking:false restores redirects. links_prepare reuses only links with the requested cloaking setting.

Cloaking requires an HTTPS destination that permits iframe embedding. Sites can block embedding through X-Frame-Options or Content-Security-Policy frame-ancestors; these restrictions are respected. If you control the destination, allow https://s.creator.gg in its frame-ancestors policy and remove conflicting framing restrictions. Test the actual destination before distributing it. Sign-in, payments, cookies and some navigation can behave differently inside a frame. Masked pages show only the destination iframe, with no original-link button or overlay controls. The destination URL remains accessible in page source; cloaking is branding, not secrecy or access control.

Tracking parameters remain on the embedded destination. A successful short-page request records one click under the existing reporting rules, even if the destination later refuses to embed; iframe navigation does not add short-link clicks. Pause, archive, expiry and security suspension still apply to subsequent short-page requests. An already loaded iframe is not remotely closed.

## Manage and retry

Use links_list and follow nextCursor even when a filtered page has no items. links_get returns the current record and up to twenty recent edits. Supply its revision to links_update or links_archive. A stale revision fails instead of overwriting newer changes. The short path cannot be renamed.

Every mutation requires a stable 8–128 character requestId. Reuse it only for identical arguments and the same authenticated actor. The link change and receipt are atomic. Identical retries return the same link ID and the current record, with the revision originally applied identified separately. A changed payload conflicts. After an uncertain response, retry the identical request or read the link before taking another action.

Pause is reversible. Archive permanently stops the redirect and retires its path; it cannot be undone. Expiry is enforced during resolution; expiresAt:null clears it. Committed edits affect subsequent resolver reads. No redirect cache or permanent browser redirect is used.

## Reporting and privacy

links_stats reports a workspace or owned link for days: 7, 30 (default), or 3months. Dates and daily groups are UTC. Analytics Engine retains a rolling three months. Counts use sampling weights, and sampled results are estimates. Clicks are not unique people. Identified crawlers/previews, HEAD requests and failed redirects are excluded. Reports update asynchronously; an unavailable report is not zero activity.

Events contain link/workspace IDs, country, device class and referrer hostname. The application does not persist visitor cookies, raw IPs, full user agents, or referrer paths/query strings. Long-term totals and conversion attribution are not included.

## Availability and limits

Initial configurable limits are 1,000 non-archived links per workspace, 100 creations per UTC day, 60 mutations per minute and 30 report requests per minute. Creation limits never disable existing redirects. Workspace disconnection blocks management while published links continue, subject to expiry, archive or a security suspension. Customer domains, bulk import and free-account management are not included in this release.