ZusCo API

Create, manage, and track short links programmatically. Everything you can do in the dashboard, you can do via the API.

Base URLhttps://zus.co/api/v1

Authentication

All API requests require a Bearer token in the Authorization header. Create API keys in your Dashboard → Settings → API Keys.

Keys use the zus_ prefix.

Example request

curl https://zus.co/api/v1/links \
  -H "Authorization: Bearer zus_xxxxxxxxxxxxxxxxxxxxx"

GET/api/v1/links

Retrieve a paginated list of links in your workspace. Supports filtering, searching, and sorting.

Query Parameters

Name	Type	Required	Description
page	integer	Optional	Page number (default: 1)
limit	integer	Optional	Results per page (default: 20, max: 100)
search	string	Optional	Search by URL, slug, or title
tag	string	Optional	Filter by tag name
folder_id	string	Optional	Filter by folder UUID
archived	boolean	Optional	Filter by archived status (true/false)
sort_by	string	Optional	Sort field: created_at, clicks, last_clicked_at, slug
sort_order	string	Optional	Sort direction: asc or desc

Request

curl "https://zus.co/api/v1/links?page=1&limit=10&sort_by=clicks&sort_order=desc" \
  -H "Authorization: Bearer zus_xxxxxxxxxxxxxxxxxxxxx"

Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "workspace_id": "...",
      "domain": "zus.co",
      "slug": "my-link",
      "url": "https://example.com",
      "title": "My Link",
      "description": null,
      "tags": ["marketing"],
      "folder_id": null,
      "password": null,
      "expires_at": null,
      "archived": false,
      "clicks": 42,
      "unique_clicks": 30,
      "last_clicked_at": "2026-03-10T15:30:00.000Z",
      "created_at": "2026-03-09T12:00:00.000Z",
      "updated_at": "2026-03-10T15:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 47,
    "pages": 5
  }
}

POST/api/v1/links

Create a new short link. Only url is required — everything else is optional. Returns 201 on success.

Request Body

Name	Type	Required	Description
url	string	Required	Destination URL
slug	string	Optional	Custom slug (auto-generated if omitted)
title	string	Optional	Link title
description	string	Optional	Link description
tags	string[]	Optional	Array of tag names
folder_id	string	Optional	Folder UUID to organize into
password	string	Optional	Password-protect the link
expires_at	string	Optional	Expiration date (ISO 8601)
utm_source	string	Optional	UTM source parameter
utm_medium	string	Optional	UTM medium parameter
utm_campaign	string	Optional	UTM campaign parameter
utm_term	string	Optional	UTM term parameter
utm_content	string	Optional	UTM content parameter

Request

curl -X POST https://zus.co/api/v1/links \
  -H "Authorization: Bearer zus_xxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/my-long-article",
    "slug": "article",
    "title": "My Article",
    "tags": ["marketing", "blog"],
    "utm_source": "twitter",
    "utm_medium": "social"
  }'

Response · 201

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "workspace_id": "...",
    "domain": "zus.co",
    "slug": "article",
    "url": "https://example.com/my-long-article",
    "title": "My Article",
    "description": null,
    "tags": ["marketing", "blog"],
    "folder_id": null,
    "password": null,
    "expires_at": null,
    "utm_source": "twitter",
    "utm_medium": "social",
    "utm_campaign": null,
    "utm_term": null,
    "utm_content": null,
    "archived": false,
    "clicks": 0,
    "unique_clicks": 0,
    "last_clicked_at": null,
    "created_at": "2026-03-10T18:00:00.000Z",
    "updated_at": "2026-03-10T18:00:00.000Z"
  },
  "short_url": "https://zus.co/article"
}

GET/api/v1/links/:id

Retrieve a single link by its UUID.

Path Parameters

Name	Type	Required	Description
id	string	Required	Link UUID

Request

curl https://zus.co/api/v1/links/550e8400-e29b-41d4-a716-446655440001 \
  -H "Authorization: Bearer zus_xxxxxxxxxxxxxxxxxxxxx"

Response

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "domain": "zus.co",
    "slug": "article",
    "url": "https://example.com/my-long-article",
    "title": "My Article",
    "clicks": 42,
    "unique_clicks": 30,
    "created_at": "2026-03-10T18:00:00.000Z",
    "..."
  },
  "short_url": "https://zus.co/article"
}

PATCH/api/v1/links/:id

Update an existing link. All fields are optional — only include what you want to change.

Path Parameters

Name	Type	Required	Description
id	string	Required	Link UUID

Request Body

Same fields as Create Link, all optional. Additionally:

Name	Type	Required	Description
archived	boolean	Optional	Archive or unarchive the link

Request

curl -X PATCH https://zus.co/api/v1/links/550e8400-e29b-41d4-a716-446655440001 \
  -H "Authorization: Bearer zus_xxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Title",
    "tags": ["marketing", "updated"]
  }'

Response

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "domain": "zus.co",
    "slug": "article",
    "url": "https://example.com/my-long-article",
    "title": "Updated Title",
    "tags": ["marketing", "updated"],
    "clicks": 42,
    "..."
  },
  "short_url": "https://zus.co/article"
}

DELETE/api/v1/links/:id

Permanently delete a link. This action cannot be undone. All associated click data will also be removed.

Path Parameters

Name	Type	Required	Description
id	string	Required	Link UUID

Request

curl -X DELETE https://zus.co/api/v1/links/550e8400-e29b-41d4-a716-446655440001 \
  -H "Authorization: Bearer zus_xxxxxxxxxxxxxxxxxxxxx"

Response

{
  "message": "Link deleted successfully"
}

GET/api/v1/links/:id/stats

Get detailed analytics for a link, including click totals, time series data, and breakdowns by country, device, browser, OS, and referrer.

Path Parameters

Name	Type	Required	Description
id	string	Required	Link UUID

Query Parameters

Name	Type	Required	Description
range	string	Optional	Time range: 24h, 7d, 30d, 90d, or all (default: 7d)

Request

curl "https://zus.co/api/v1/links/550e8400-e29b-41d4-a716-446655440001/stats?range=30d" \
  -H "Authorization: Bearer zus_xxxxxxxxxxxxxxxxxxxxx"

Response

{
  "data": {
    "link": {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "slug": "article",
      "url": "https://example.com/my-long-article"
    },
    "range": "30d",
    "period": {
      "start": "2026-02-08T00:00:00.000Z",
      "end": "2026-03-10T23:59:59.999Z"
    },
    "totals": {
      "clicks": 1284,
      "unique_clicks": 923,
      "bot_clicks": 47,
      "human_clicks": 1237,
      "avg_clicks_per_day": 42.8
    },
    "clicks_over_time": [
      { "date": "2026-02-08", "clicks": 31, "unique_clicks": 24 },
      { "date": "2026-02-09", "clicks": 45, "unique_clicks": 38 }
    ],
    "breakdowns": {
      "countries": [
        { "country": "US", "clicks": 634 },
        { "country": "GB", "clicks": 201 }
      ],
      "devices": [
        { "device": "Desktop", "clicks": 782 },
        { "device": "Mobile", "clicks": 502 }
      ],
      "browsers": [
        { "browser": "Chrome", "clicks": 612 },
        { "browser": "Safari", "clicks": 389 }
      ],
      "operating_systems": [
        { "os": "Windows", "clicks": 445 },
        { "os": "Mac OS", "clicks": 337 }
      ],
      "referrers": [
        { "referrer": "twitter.com", "clicks": 312 },
        { "referrer": "direct", "clicks": 289 }
      ]
    }
  }
}

Link Object

The standard link object returned across all endpoints.

Field	Type	Description
id	string	Unique UUID identifier
workspace_id	string	Workspace UUID
domain	string	Short link domain (e.g., zus.co)
slug	string	Short link slug
url	string	Destination URL
title	string \| null	Link title
description	string \| null	Link description
tags	string[]	Array of tag names
folder_id	string \| null	Folder UUID
password	string \| null	Password (if protected)
expires_at	string \| null	Expiration date (ISO 8601)
utm_source	string \| null	UTM source parameter
utm_medium	string \| null	UTM medium parameter
utm_campaign	string \| null	UTM campaign parameter
utm_term	string \| null	UTM term parameter
utm_content	string \| null	UTM content parameter
archived	boolean	Whether the link is archived
clicks	integer	Total click count
unique_clicks	integer	Unique click count (by IP, 24h window)
last_clicked_at	string \| null	Last click timestamp (ISO 8601)
created_at	string	Creation timestamp (ISO 8601)
updated_at	string	Last update timestamp (ISO 8601)

Error Responses

The API uses standard HTTP status codes. Errors return a JSON body with an error field.

Status	Meaning	Example
400	Bad Request	Invalid parameters or missing required fields
401	Unauthorized	Invalid or missing API key
404	Not Found	The requested resource does not exist
500	Internal Server Error	Something went wrong on our end

Error response format

{
  "error": "Invalid API key"
}

During the current beta period, rate limits are generous and no hard limits are enforced. We ask that you keep requests reasonable — a few hundred per minute should be more than enough for most use cases.

If you need higher throughput for a specific integration, reach out and we'll work with you.

Need help? support@zus.co