Build short links with a small, explicit API.

Send an active workspace key as a Bearer credential. Keys begin with urlme_live_ in production and are displayed only once. Store them in a secret manager or environment variable; never include one in browser or mobile application code.

Authorization: Bearer $URLME_API_KEY

POST /v1/links accepts a destination plus optional private metadata, UTM parameters, and expiration. Without a custom domain, URLMe always allocates a seven-character code automatically.

curl --request POST "https://api.urlme.link/v1/links" \
  --header "Authorization: Bearer $URLME_API_KEY" \
  --header "Idempotency-Key: welcome-campaign-2026" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://example.com/campaign/welcome",
    "description": "Welcome campaign",
    "tags": ["email", "onboarding"],
    "utm": { "source": "newsletter", "medium": "email", "campaign": "welcome" },
    "expiresAt": "2026-12-31T23:59:59Z"
  }'

{
  "data": {
    "id": "3OiMpZk866QrFxm0l5p0",
    "code": "welcome",
    "shortUrl": "https://go.example.com/welcome",
    "destination": "https://example.com/onboarding",
    "description": "Customer onboarding",
    "tags": ["onboarding"],
    "clicks": 0,
    "status": "active",
    "createdAt": "2026-07-29T14:22:31.381Z",
    "expiresAt": null
  }
}

Send an Idempotency-Key header of 8-128 characters on create requests. URLMe retains the key for 24 hours. Retrying the same body replays the original link without increasing usage; reusing the key with a different body returns 409.

POST /v1/links/bulk accepts a links array and returns one result per item. Batch sizes are deliberately capped at 25 for Starter, 100 for Growth, and 250 for Scale. A partial result uses HTTP 207, and only successfully created links consume the link allowance.

Custom aliases are deliberately unavailable on urlme.link. Growth and Scale workspaces may send customCode only together with an active, connected custom-domain domain.

• 4-32 characters: letters, numbers, underscore, or hyphen.
• Aliases preserve case and are unique per hostname.
• Reserved aliases are checked case-insensitively.
• A duplicate returns 409 code_unavailable; the existing link is never overwritten.
• Omit customCode to receive an automatic code on the custom domain.

curl --request POST "https://api.urlme.link/v1/links" \
  --header "Authorization: Bearer $URLME_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://example.com/onboarding",
    "description": "Customer onboarding",
    "tags": ["onboarding"],
    "domain": "go.example.com",
    "customCode": "welcome"
  }'

GET /v1/links returns newest-first records and omits deleted links. The current API does not expose cursor pagination; use limit up to 100.

URLMe exposes the same workspace through a Streamable HTTP MCP endpoint at https://api.urlme.link/mcp. Authenticate with a workspace API key. MCP calls inherit the same subscription state, quotas, destination checks, custom-domain ownership, and alias rules as REST calls.

URL: https://api.urlme.link/mcp
Authorization: Bearer $URLME_API_KEY

This API-key endpoint works with compatible MCP clients and developer tooling. A publicly listed URLMe app inside ChatGPT requires a separate per-user OAuth connection and OpenAI app review; a workspace API key alone does not install or authorize a public ChatGPT app.

Link creation and redirects are counted in the current workspace usage window. Existing links continue to consume redirect allowance when opened in later periods. Paid usage windows align with Stripe billing periods; allowances reset when the next period begins.

Non-2xx JSON responses use { error: { code, message } }. Branch on error.code, not the human-readable message.

{
  "error": {
    "code": "code_unavailable",
    "message": "That short code is already in use on this domain."
  }
}

API-key creation and revocation, custom-domain DNS and certificate provisioning, billing checkout, and the Stripe portal require an authenticated owner or admin session. They are customer-facing management operations, but they do not accept a workspace API key and are intentionally excluded from unattended integration examples.