Endpoints
Complete endpoint documentation for the Cutly API. Detailed information about all available endpoints, parameters, and responses.
Short Links
The Short Links API allows you to create, manage, and track shortened URLs. All endpoints require API key authentication.
POST /api/v1/short-links
Create a new short link
Request Body
{
"original_url": "https://example.com/very-long-url", // Required
"custom_alias": "my-custom-link", // Optional
"title": "My Short Link", // Optional
"description": "A description of the link", // Optional
"tags": ["marketing", "social"] // Optional array
}Response
{
"success": true,
"data": {
"id": "uuid-here",
"short_code": "abc123",
"original_url": "https://example.com/very-long-url",
"short_url": "https://cutly.xyz/r/abc123",
"created_at": "2024-01-01T00:00:00Z"
}
}Example cURL
📄Create Short Link | cURL
1curl -X POST "https://cutly.xyz/api/v1/short-links" \
2 -H "Content-Type: application/json" \
3 -H "X-API-Key: your_api_key_here" \
4 -d '{
5 "original_url": "https://example.com/very-long-url",
6 "title": "My Short Link"
7 }'GET /api/v1/short-links
List all short links with pagination and search
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| limit | integer | 50 | Number of items per page (max: 100) |
| offset | integer | 0 | Number of items to skip |
| search | string | - | Search in title, description, or short_code |
Response
{
"success": true,
"data": [
{
"id": "uuid-here",
"short_code": "abc123",
"original_url": "https://example.com/very-long-url",
"title": "My Short Link",
"description": "A description",
"tags": ["marketing"],
"click_count": 42,
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z"
}
],
"pagination": {
"limit": 50,
"offset": 0,
"total": 100
}
}QR Codes
Generate and customize QR codes for your short links with various styling options.
POST /api/qr-codes
Create a new QR code
Request Body
{
"short_link_id": "uuid-here", // Required
"name": "My QR Code", // Required
"size": 300, // Optional, default: 300
"foreground_color": "#000000", // Optional, default: #000000
"background_color": "#FFFFFF", // Optional, default: #FFFFFF
"corner_square_color": "#000000", // Optional
"corner_dot_color": "#000000", // Optional
"logo_url": "https://example.com/logo.png", // Optional
"logo_filename": "logo.png", // Optional
"settings": {} // Optional additional settings
}Response
{
"success": true,
"data": {
"id": "qr-uuid-here",
"short_link_id": "link-uuid-here",
"name": "My QR Code",
"qr_code_url": "https://cutly.xyz/r/abc123",
"size": 300,
"foreground_color": "#000000",
"background_color": "#FFFFFF",
"created_at": "2024-01-01T00:00:00Z"
}
}Custom Domains
Manage custom domains for branded short URLs. Requires Pro or Business plan.
POST /api/custom-domains
Add a new custom domain
Request Body
{
"domain": "mybrand.com" // Required
}Response
{
"success": true,
"data": {
"id": "domain-uuid-here",
"domain": "mybrand.com",
"is_verified": false,
"verification_token": "abc123...",
"dns_records": {
"cname": "cutly.xyz",
"txt": "cutly-verification=abc123..."
},
"ssl_status": "pending",
"created_at": "2024-01-01T00:00:00Z"
},
"verification_instructions": {
"domain": "mybrand.com",
"cname_record": "cutly.xyz",
"txt_record": "cutly-verification=abc123..."
}
}Analytics
Access click analytics and API usage data for your account.
GET /api/click-analytics
Get click analytics data
Response
{
"success": true,
"data": [
{
"id": "analytics-uuid-here",
"short_link_id": "link-uuid-here",
"clicked_at": "2024-01-01T12:00:00Z",
"ip_address": "192.168.1.1",
"user_agent": "Mozilla/5.0...",
"referer": "https://google.com",
"country": "US",
"city": "New York",
"device_type": "desktop",
"browser": "Chrome",
"os": "Windows"
}
]
}Team Management
Manage team members and invitations. Requires Pro or Business plan.
POST /api/team-members/invite
Invite a new team member
Request Body
{
"email": "newmember@example.com", // Required
"role": "member" // Required: "member" or "admin"
}Response
{
"success": true,
"data": {
"id": "invitation-uuid-here",
"email": "newmember@example.com",
"role": "member",
"token": "invitation-token-here",
"expires_at": "2024-01-08T00:00:00Z",
"is_accepted": false
},
"message": "Invitation sent",
"emailSent": true
}API Keys
Manage your API keys for programmatic access to the Cutly API.
POST /api/api-keys
Create a new API key
Request Body
{
"name": "My API Key" // Required
}Response
{
"success": true,
"data": {
"id": "key-uuid-here",
"name": "My API Key",
"key_prefix": "abc12345",
"api_key": "abc12345...full-key-here",
"is_active": true,
"created_at": "2024-01-01T00:00:00Z"
}
}Important
The full API key is only returned once when created. Store it securely as it cannot be retrieved later.
Custom Pages
Create and manage custom landing pages for your short links.
POST /api/custom-pages
Create a new custom page
Request Body
{
"name": "My Landing Page", // Required
"slug": "my-landing-page", // Required
"template_type": "free", // Optional: "free" or "paid"
"template_name": "basic", // Required
"title": "Welcome to My Page", // Required
"description": "Page description", // Optional
"content": {}, // Optional: Page content object
"settings": {}, // Optional: Page settings
"favicon_filename": "favicon.ico", // Optional
"og_image_filename": "og-image.jpg" // Optional
}Billing
Manage subscriptions and billing through Stripe integration.
POST /api/stripe/create-checkout
Create a Stripe checkout session
Request Body
{
"priceId": "price_1234567890", // Required: Stripe price ID
"planType": "pro", // Required: "starter", "pro", or "business"
"isUpgrade": false, // Optional: true for upgrades
"isDowngrade": false // Optional: true for downgrades
}Response
{
"sessionId": "cs_test_1234567890",
"url": "https://checkout.stripe.com/pay/cs_test_1234567890"
}Can't find what you're looking for? Contact our support team
On this page