LinksCreate link

Create link

Create a short link. Requires an agency key (ak_). An initial uptime check runs synchronously and its result is returned under uptime.

curl -X POST "https://mythic-analytics.gulp.workers.dev/client/v1/links?location_id=example_string" \
  -H "Content-Type: application/json" \
  -H "X-Location-Id: example_string" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
  "destination_url": "https://acme-retail.com/summer-sale",
  "slug": "summer-sale",
  "title": "Summer Sale Campaign",
  "redirect_type": 42,
  "enabled": true,
  "utm_passthrough": true,
  "metadata": {},
  "expires_at": "2024-12-25T10:00:00Z"
}'
{
  "success": true,
  "data": {
    "id": "4f9a2c1e-8b3d-4e7a-9c2f-1a2b3c4d5e6f",
    "location_id": "acme-retail",
    "slug": "summer-sale",
    "destination_url": "https://acme-retail.com/summer-sale",
    "title": "Summer Sale Campaign",
    "redirect_type": 302,
    "enabled": true,
    "utm_passthrough": true,
    "metadata": {},
    "expires_at": "2024-12-25T10:00:00Z",
    "created_at": "2024-06-01T12:00:00.000Z",
    "updated_at": "2024-06-15T08:30:00.000Z",
    "click_count": 1247,
    "uptime": {
      "is_up": true,
      "status_code": 200,
      "response_time_ms": 142,
      "error_type": null,
      "error_message": null,
      "checked_at": "2024-06-01T12:00:00.500Z"
    }
  }
}
POST
/links
POST
Base URLstring

Target server for requests. Edit to use your own host.

Bearer Token
Bearer Tokenstring
Required

Client API key as a bearer token. Use an agency key (ak_..., read-write) or a location secret key (sk_..., read-only). Format: Bearer ak_... or Bearer sk_.... Scoped keys (mcp_) are accepted too and need links:read or links:write. See Using an mcp_ key over HTTP.

Client API key as a bearer token. Use an agency key (ak_..., read-write) or a location secret key (sk_..., read-only). Format: Bearer ak_... or Bearer sk_.... Scoped keys (mcp_) are accepted too and need links:read or links:write. See Using an mcp_ key over HTTP.
query
location_idstring

Target location (client) id. Required when authenticating with an agency key (ak_); alternative to the X-Location-Id header. Ignored for secret keys, which resolve their own location.

Content-Typestring
Required

The media type of the request body

Options: application/json
header
X-Location-Idstring

Target location (client) id. Required when authenticating with an agency key (ak_); alternative to the location_id query parameter. Ignored for secret keys.

destination_urlstring
Required

Target URL. Must start with http:// or https://.

Format: uri
slugstring

Custom slug, 1-128 chars of [a-zA-Z0-9_-]. Auto-generated by the database if omitted.

titlestring

Human-readable title.

redirect_typeinteger

HTTP redirect status. Defaults to 302.

Options: 301, 302
enabledboolean

Whether the link is active.

utm_passthroughboolean

Whether inbound UTM parameters are forwarded to the destination.

metadataobject

Arbitrary JSON metadata.

expires_atstring

Optional expiration timestamp.

Format: date-time
Request Preview
Response

Response will appear here after sending the request

Authentication

header
Authorizationstring
Required

Bearer token. Client API key as a bearer token. Use an agency key (ak_..., read-write) or a location secret key (sk_..., read-only). Format: Bearer ak_... or Bearer sk_.... Scoped keys (mcp_) are accepted too and need links:read or links:write. See Using an mcp_ key over HTTP.

Query Parameters

location_idstring

Target location (client) id. Required when authenticating with an agency key (ak_); alternative to the X-Location-Id header. Ignored for secret keys, which resolve their own location.

Headers

X-Location-Idstring

Target location (client) id. Required when authenticating with an agency key (ak_); alternative to the location_id query parameter. Ignored for secret keys.

Body

application/json
destination_urlstring
Required

Target URL. Must start with http:// or https://.

Example:
https://acme-retail.com/summer-sale
slugstring

Custom slug, 1-128 chars of [a-zA-Z0-9_-]. Auto-generated by the database if omitted.

Example:
summer-sale
titlestring

Human-readable title.

Example:
Summer Sale Campaign
redirect_typeinteger

HTTP redirect status. Defaults to 302.

Allowed values:301302
enabledboolean

Whether the link is active.

utm_passthroughboolean

Whether inbound UTM parameters are forwarded to the destination.

metadataobject

Arbitrary JSON metadata.

expires_atstring

Optional expiration timestamp.

Responses