API Reference

Links API

API endpoints for managing short links

Create and manage short links programmatically.

Create Link

Create a new short link.

POST /v1/links

Request Body

Parameter	Type	Required	Description
`url`	string	Yes	The destination URL
`slug`	string	No	Custom slug (auto-generated if not provided)
`title`	string	No	Link title for analytics
`startsAt`	string	No	Start date (ISO 8601)
`expiresAt`	string	No	Expiration date (ISO 8601)
`clickLimit`	number	No	Maximum number of clicks allowed
`expirationUrl`	string	No	URL to redirect to after expiration
`utmSource`	string	No	UTM source parameter
`utmMedium`	string	No	UTM medium parameter
`utmCampaign`	string	No	UTM campaign parameter
`appLinkingEnabled`	boolean	No	Enable deep linking for supported apps
`iosEnabled`	boolean	No	Enable App Linking for iOS
`androidEnabled`	boolean	No	Enable App Linking for Android
`redirectDelayEnabled`	boolean	No	Enable a 5-second delay before redirecting

Example Usage

interface CreateLinkRequest {
  url: string;
  slug?: string;
  title?: string;
  startsAt?: string;
  expiresAt?: string;
  clickLimit?: number;
  expirationUrl?: string;
  utmSource?: string;
  utmMedium?: string;
  utmCampaign?: string;
  appLinkingEnabled?: boolean;
  iosEnabled?: boolean;
  androidEnabled?: boolean;
  redirectDelayEnabled?: boolean;
}

interface LinkResponse {
  id: string;
  url: string;
  slug: string;
  shortUrl: string;
  title: string;
  clicks: number;
  createdAt: string;
  startsAt: string | null;
  expiresAt: string | null;
  clickLimit: number | null;
  expirationUrl: string | null;
  utmSource: string | null;
  utmMedium: string | null;
  utmCampaign: string | null;
  appLinkingEnabled: boolean;
  iosEnabled: boolean;
  androidEnabled: boolean;
  redirectDelayEnabled: boolean;
}

interface ApiResponse<T> {
  success: boolean;
  data: T;
}

<script setup lang="ts">
const createLink = async () => {
  const response = await fetch("https://api.linked.is/v1/links", {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      url: "https://example.com/my-long-url",
      slug: "my-link",
      title: "My Example Link",
      startsAt: "2024-02-01T00:00:00Z",
      clickLimit: 1000,
      utmSource: "newsletter",
    }),
  });

  const data = await response.json();
  console.log(data);
  return data;
};
</script>

<template>
  <div>
    <button @click="createLink">Create Link</button>
  </div>
</template>

import requests

url = "https://api.linked.is/v1/links"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
}
payload = {
    "url": "https://example.com/my-long-url",
    "slug": "my-link",
    "title": "My Example Link",
    "startsAt": "2024-02-01T00:00:00Z",
    "clickLimit": 1000,
    "utmSource": "newsletter"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

curl -X POST "https://api.linked.is/v1/links" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/my-long-url",
    "slug": "my-link",
    "title": "My Example Link",
    "startsAt": "2024-02-01T00:00:00Z",
    "clickLimit": 1000,
    "utmSource": "newsletter"
  }'

Response Example

<script setup lang="ts">
const linkResponse = {
  success: true,
  data: {
    id: "clx1234567890",
    url: "https://example.com/my-long-url",
    slug: "my-link",
    shortUrl: "https://linked.is/my-link",
    title: "My Example Link",
    clicks: 0,
    createdAt: "2024-01-15T10:30:00Z",
    startsAt: "2024-02-01T00:00:00Z",
    expiresAt: null,
    clickLimit: 1000,
    expirationUrl: null,
    utmSource: "newsletter",
    utmMedium: "email",
    utmCampaign: null,
  },
};
</script>

<template>
  <pre>{{ JSON.stringify(linkResponse, null, 2) }}</pre>
</template>

Get Link

Retrieve a specific link by ID.

GET /v1/links/:id

Example Usage

<script setup lang="ts">
const getLink = async () => {
  const response = await fetch("https://api.linked.is/v1/links/clx1234567890", {
    headers: {
      Authorization: "Bearer YOUR_API_TOKEN",
    },
  });

  const data = await response.json();
  console.log(data);
  return data;
};
</script>

<template>
  <div>
    <button @click="getLink">Get Link</button>
  </div>
</template>

import requests

url = "https://api.linked.is/v1/links/clx1234567890"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN"
}

response = requests.get(url, headers=headers)
print(response.json())

curl -X GET "https://api.linked.is/v1/links/clx1234567890" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response Example

<script setup lang="ts">
const linkResponse = {
  success: true,
  data: {
    id: "clx1234567890",
    url: "https://example.com/my-long-url",
    slug: "my-link",
    shortUrl: "https://linked.is/my-link",
    title: "My Example Link",
    clicks: 42,
    createdAt: "2024-01-15T10:30:00Z",
    expiresAt: null,
  },
};
</script>

<template>
  <pre>{{ JSON.stringify(linkResponse, null, 2) }}</pre>
</template>

Update Link

Update an existing link.

PATCH /v1/links/:id

Request Body

Parameter	Type	Description
`url`	string	The destination URL
`slug`	string	Custom slug
`title`	string	Link title
`startsAt`	string	Start date (ISO 8601)
`expiresAt`	string	Expiration date (ISO 8601)
`clickLimit`	number	Maximum number of clicks allowed
`expirationUrl`	string	URL to redirect to after expiration
`utmSource`	string	UTM source parameter
`utmMedium`	string	UTM medium parameter
`utmCampaign`	string	UTM campaign parameter
`appLinkingEnabled`	boolean	Enable deep linking for supported apps
`iosEnabled`	boolean	Enable App Linking for iOS
`androidEnabled`	boolean	Enable App Linking for Android
`redirectDelayEnabled`	boolean	Enable a 5-second delay before redirecting

Example Usage

<script setup lang="ts">
const updateLink = async () => {
  const response = await fetch("https://api.linked.is/v1/links/clx1234567890", {
    method: "PATCH",
    headers: {
      Authorization: "Bearer YOUR_API_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      title: "Updated Title",
      clickLimit: 5000,
      utmCampaign: "summer_sale",
    }),
  });

  const data = await response.json();
  console.log(data);
  return data;
};
</script>

<template>
  <div>
    <button @click="updateLink">Update Link</button>
  </div>
</template>

import requests

url = "https://api.linked.is/v1/links/clx1234567890"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
}
payload = {
    "title": "Updated Title",
    "clickLimit": 5000,
    "utmCampaign": "summer_sale"
}

response = requests.patch(url, json=payload, headers=headers)
print(response.json())

curl -X PATCH "https://api.linked.is/v1/links/clx1234567890" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Title",
    "clickLimit": 5000,
    "utmCampaign": "summer_sale"
  }'

Response Example

<script setup lang="ts">
const updateResponse = {
  success: true,
  data: {
    id: "clx1234567890",
    url: "https://example.com/new-url",
    slug: "my-link",
    shortUrl: "https://linked.is/my-link",
    title: "Updated Title",
    clicks: 42,
    createdAt: "2024-01-15T10:30:00Z",
    updatedAt: "2024-01-16T14:20:00Z",
    startsAt: null,
    expiresAt: null,
    clickLimit: 5000,
    expirationUrl: null,
    utmSource: null,
    utmMedium: null,
    utmCampaign: "summer_sale",
  },
};
</script>

<template>
  <pre>{{ JSON.stringify(updateResponse, null, 2) }}</pre>
</template>

Delete Link

Delete a link permanently.

DELETE /v1/links/:id

Example Usage

<script setup lang="ts">
const deleteLink = async () => {
  const response = await fetch("https://api.linked.is/v1/links/clx1234567890", {
    method: "DELETE",
    headers: {
      Authorization: "Bearer YOUR_API_TOKEN",
    },
  });

  const data = await response.json();
  console.log(data);
  return data;
};
</script>

<template>
  <div>
    <button @click="deleteLink" class="danger">Delete Link</button>
  </div>
</template>

import requests

url = "https://api.linked.is/v1/links/clx1234567890"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN"
}

response = requests.delete(url, headers=headers)
print(response.json())

curl -X DELETE "https://api.linked.is/v1/links/clx1234567890" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response Example

<script setup lang="ts">
const deleteResponse = {
  success: true,
  data: {
    deleted: true,
  },
};
</script>

<template>
  <pre>{{ JSON.stringify(deleteResponse, null, 2) }}</pre>
</template>

List Links

Get a paginated list of all your links.

GET /v1/links

Query Parameters

Parameter	Type	Default	Description
`page`	number	1	Page number
`limit`	number	20	Items per page (max 100)
`search`	string	-	Search by title or slug
`sort`	string	`createdAt`	Sort field
`order`	string	`desc`	Sort order (`asc` or `desc`)

Example Usage

<script setup lang="ts">
const listLinks = async () => {
  const response = await fetch(
    "https://api.linked.is/v1/links?page=1&limit=10&sort=clicks&order=desc",
    {
      headers: {
        Authorization: "Bearer YOUR_API_TOKEN",
      },
    },
  );

  const data = await response.json();
  console.log(data);
  return data;
};
</script>

<template>
  <div>
    <button @click="listLinks">List Links</button>
  </div>
</template>

import requests

url = "https://api.linked.is/v1/links"
params = {
    "page": 1,
    "limit": 10,
    "sort": "clicks",
    "order": "desc"
}
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN"
}

response = requests.get(url, params=params, headers=headers)
print(response.json())

curl -X GET "https://api.linked.is/v1/links?page=1&limit=10&sort=clicks&order=desc" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response Example

<script setup lang="ts">
const listResponse = {
  success: true,
  data: {
    items: [
      {
        id: "clx1234567890",
        url: "https://example.com/my-long-url",
        slug: "my-link",
        shortUrl: "https://linked.is/my-link",
        title: "My Example Link",
        clicks: 42,
        createdAt: "2024-01-15T10:30:00Z",
      },
    ],
    pagination: {
      page: 1,
      limit: 10,
      total: 25,
      totalPages: 3,
    },
  },
};
</script>

<template>
  <pre>{{ JSON.stringify(listResponse, null, 2) }}</pre>
</template>

Get QR Code

Generate a QR code image for a short link.

GET /v1/links/:id/qr

Query Parameters

Parameter	Type	Default	Description
`size`	number	256	Image size in pixels (100-1000)
`format`	string	`png`	Output format: `png`, `svg`, or `base64`
`margin`	number	2	Quiet zone margin (0-10)
`dark`	string	`#000000`	Dark/foreground color (hex)
`light`	string	`#ffffff`	Light/background color (hex)

Example Usage

<script setup lang="ts">
const getQrCodeBase64 = async () => {
  const response = await fetch(
    "https://api.linked.is/v1/links/clx1234567890/qr?format=base64",
    {
      headers: {
        Authorization: "Bearer YOUR_API_TOKEN",
      },
    },
  );

  const { data } = await response.json();
  console.log(data.qrCode); // data:image/png;base64,...
  return data;
};
</script>

<template>
  <div>
    <button @click="getQrCodeBase64">Get QR Code (Base64)</button>
  </div>
</template>

import requests

url = "https://api.linked.is/v1/links/clx1234567890/qr"
params = {"size": 512, "format": "png"}
headers = {"Authorization": "Bearer YOUR_API_TOKEN"}

response = requests.get(url, params=params, headers=headers)
with open("qrcode.png", "wb") as f:
    f.write(response.content)

# Save as image file
curl -X GET "https://api.linked.is/v1/links/clx1234567890/qr?size=512" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --output qrcode.png

# Get Base64 JSON
curl -X GET "https://api.linked.is/v1/links/clx1234567890/qr?format=base64" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response Examples

<script setup lang="ts">
const qrResponse = {
  success: true,
  data: {
    url: "https://linked.is/my-link",
    qrCode: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    format: "base64",
    size: 256,
  },
};
</script>

<template>
  <pre>{{ JSON.stringify(qrResponse, null, 2) }}</pre>
</template>

The response will be the raw image binary with the appropriate Content-Type header (e.g., image/png or image/svg+xml).

# Red QR code on white background
curl -X GET "https://api.linked.is/v1/links/clx1234567890/qr?dark=%23ff0000&light=%23ffffff" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --output qrcode.png

<script setup lang="ts">
const generateCustomQR = async () => {
  // This would generate a red QR code on white background
  const url =
    "https://api.linked.is/v1/links/clx1234567890/qr?dark=%23ff0000&light=%23ffffff";
  console.log("Custom QR URL:", url);
  return url;
};
</script>

<template>
  <div>
    <button @click="generateCustomQR">Generate Custom QR</button>
  </div>
</template>

Note: For png and svg formats, the response is the raw image data with appropriate Content-Type header. For base64 format, the response is a JSON object containing the data URL.


## Error Codes

| Code             | Description                       |
| ---------------- | --------------------------------- |
| `LINK_NOT_FOUND` | The specified link does not exist |
| `SLUG_TAKEN`     | The slug is already in use        |
| `INVALID_URL`    | The provided URL is not valid     |
| `LINK_EXPIRED`   | The link has expired              |

Authentication

Learn how to authenticate with the linked.is API

LLM Integration

How LLMs and AI agents can use the linked.is API

Links API

Create Link

Request Body

Example Usage

Response Example

Get Link

Example Usage

Response Example

Update Link

Request Body

Example Usage

Response Example

Delete Link

Example Usage

Response Example

List Links

Query Parameters

Example Usage

Response Example

Get QR Code

Query Parameters

Example Usage

Response Examples

Custom Colors Example

Success Response:

Error Response:

Rate Limit Headers:

API Response:

Create Short Link Schema:

Get Link Analytics Schema:

MCP Integration Schema:

Rate Limit Headers: