Clypt API Documentation
Build integrations with the Clypt link intelligence platform. Create short links, track analytics, organize with tags and folders — all programmatically.
RESTful API
Standard JSON REST endpoints. Use from any language or platform.
Scoped API Keys
Fine-grained permissions with read/write scopes per resource.
Rich Analytics
Geo, device, browser, and referrer breakdowns with time-series data.
Base URL
https://clypt.io/api/v1Authentication
All API requests require authentication via a Bearer token. Generate an API key from your Settings page or the POST /api/v1/keys endpoint.
curl -X GET "https://clypt.io/api/v1/links" \
-H "Authorization: Bearer clypt_your_api_key"Available Scopes
| Scope | Description |
|---|---|
| links:read | Read links — list, search, get details |
| links:write | Create, update, and delete links |
| analytics:read | Read click analytics and performance data |
| tags:read | List tags |
| tags:write | Create and manage tags |
| folders:read | List folders |
| folders:write | Create and manage folders |
Rate Limiting
API key requests are rate-limited. Check the response headers to track your usage:
X-RateLimit-Limit: 1000 # Max requests per window
X-RateLimit-Remaining: 987 # Requests remaining
X-RateLimit-Reset: 1710612000 # Window reset (Unix timestamp)Quick Start
Get up and running in under a minute. Here are examples in popular languages.
cURL
# Shorten a URL
curl -X POST "https://clypt.io/api/v1/links" \
-H "Authorization: Bearer clypt_your_api_key" \
-H "Content-Type: application/json" \
-d '{ "url": "https://example.com/my-page" }'JavaScript / TypeScript
const API_KEY = "clypt_your_api_key";
// Create a short link
const response = await fetch("https://clypt.io/api/v1/links", {
method: "POST",
headers: {
"Authorization": `Bearer ${API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
url: "https://example.com/my-page",
title: "My Page",
utmSource: "api",
}),
});
const link = await response.json();
console.log(link.shortUrl); // https://clypt.io/aBcDeFgPython
import requests
API_KEY = "clypt_your_api_key"
BASE_URL = "https://clypt.io/api/v1"
# Create a short link
response = requests.post(
f"{BASE_URL}/links",
headers={"Authorization": f"Bearer {API_KEY}"},
json={
"url": "https://example.com/my-page",
"title": "My Page",
},
)
link = response.json()
print(link["shortUrl"]) # https://clypt.io/aBcDeFg
# Get analytics
analytics = requests.get(
f"{BASE_URL}/analytics?period=7d",
headers={"Authorization": f"Bearer {API_KEY}"},
).json()
print(f"Total clicks: {analytics['totalClicks']}")
print(f"Clicks this week: {analytics['clicksInPeriod']}")Links
Create, list, and manage shortened links. Each link gets a unique short code and tracks click analytics automatically.
Analytics
Retrieve aggregate analytics across all your links — click counts, geographic distribution, device breakdowns, and time-series data.
Folders
Group links into hierarchical folders. Folders support nesting via the parentId field.
API Keys
Manage API keys programmatically. Key creation requires browser session authentication (cannot be done with an API key). You can have up to 10 active keys.
Error Handling
The API uses standard HTTP status codes. Errors return a JSON object with an error field.
{
"error": "url is required"
}| Status | Meaning |
|---|---|
200 | Success |
201 | Resource created |
400 | Bad request — missing or invalid parameters |
401 | Unauthorized — invalid or missing API key |
403 | Forbidden — insufficient scope for this action |
404 | Resource not found |
409 | Conflict — duplicate resource (e.g., custom code taken, tag name exists) |
429 | Rate limit exceeded — slow down and retry after the reset window |
500 | Internal server error — contact support if persistent |
MCP Server
Clypt also provides an MCP (Model Context Protocol) server for AI assistant integrations. The MCP server exposes all Clypt functionality as tools that AI assistants can invoke.
Installation
npm install clypt-mcp