API Reference
Complete API documentation for the Cutly platform. Learn how to integrate with our URL shortening, QR code generation, and analytics services.
Introduction
The Cutly API provides programmatic access to all platform features including URL shortening, QR code generation, custom domains, analytics, and team management. Our RESTful API is designed to be simple, consistent, and powerful.
- • URL shortening with custom aliases
- • QR code generation and customization
- • Custom domain management
- • Click analytics and tracking
- • Team member management
- • Password-protected links
- • API key authentication
- • Rate limiting protection
- • HTTPS encryption
- • Tenant isolation
- • Role-based permissions
- • Usage tracking
Authentication
All API requests require authentication using an API key. API keys are tenant-specific and provide access to all resources within your organization.
API Key Format
API keys are 64-character alphanumeric strings. Include your API key in the request header:
X-API-Key: your_api_key_here
Getting Your API Key
- Log into your Cutly dashboard
- Navigate to the APIs section
- Click "Create API Key"
- Give your key a descriptive name
- Copy the generated key (it's only shown once)
Permissions
Base URL
All API endpoints are relative to the base URL:
https://cutly.xyz
Environment
The base URL automatically adjusts based on your environment. Production uses the live domain, while development uses localhost.
Rate Limits
Rate limits are applied per API key to ensure fair usage and system stability.
Plan | Requests/Minute | Requests/Day |
---|---|---|
Free | 60 | 1,000 |
Starter | 300 | 10,000 |
Pro | 1,000 | 100,000 |
Business | 5,000 | 1,000,000 |
Rate Limit Exceeded
When rate limits are exceeded, the API returns a 429 status code with the following response:
{
"error": "Rate limit exceeded",
"retry_after": 60
}
API Endpoints Overview
The Cutly API is organized into logical resource groups. Each endpoint supports specific HTTP methods and returns consistent JSON responses.
POST /api/v1/short-links
Create
GET /api/v1/short-links
List
PUT /api/short-links/[id]
Update
DELETE /api/short-links/[id]
Delete
POST /api/qr-codes
Create
GET /api/qr-codes
List
GET /api/qr-codes/[id]
Get
PUT /api/qr-codes/[id]
Update
DELETE /api/qr-codes/[id]
Delete
GET /api/custom-domains
List
POST /api/custom-domains
Create
DELETE /api/custom-domains
Delete
GET /api/click-analytics
Click Data
GET /api/api-usage
API Usage
GET /api/qr-analytics
API Usage
GET /api/page-analytics
API Usage
GET /api/team-members
List
POST /api/team-members/invite
Invite
DELETE /api/team-members/[id]
Remove
GET /api/api-keys
List
POST /api/api-keys
Create
DELETE /api/api-keys/[id]
Delete
Response Format
All API responses follow a consistent JSON format for easy parsing and error handling.
Success Response
{
"success": true,
"data": {
// Response data here
},
"pagination": {
"limit": 50,
"offset": 0,
"total": 100
}
}
Error Response
{
"error": "Error message description",
"details": "Additional error details (optional)"
}
Pagination
List endpoints support pagination with the following query parameters:
- •
limit
- Number of items per page (default: 50, max: 100) - •
offset
- Number of items to skip (default: 0) - •
search
- Search term for filtering results
Error Handling
The API uses standard HTTP status codes to indicate success or failure of requests.
Status Code | Description | Common Causes |
---|---|---|
200 | Success | Request completed successfully |
201 | Created | Resource created successfully |
400 | Bad Request | Invalid request data or missing required fields |
401 | Unauthorized | Missing or invalid API key |
403 | Forbidden | Insufficient permissions |
404 | Not Found | Resource doesn't exist |
409 | Conflict | Resource already exists (e.g., duplicate alias) |
429 | Too Many Requests | Rate limit exceeded |
500 | Internal Server Error | Server error or database issue |
Quick Start
Get started with the Cutly API in just a few steps. Here's a simple example to create your first short link.
1. Create a Short Link
curl -X POST "https://cutly.xyz/api/v1/short-links" \ -H "Content-Type: application/json" \ -H "X-API-Key: your_api_key_here" \ -d '{ "original_url": "https://example.com/very-long-url", "title": "My Short Link", "description": "A description of the link" }'
2. 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"
}
}
3. Generate a QR Code
curl -X POST "https://cutly.xyz/api/qr-codes" \ -H "Content-Type: application/json" \ -H "X-API-Key: your_api_key_here" \ -d '{ "short_link_id": "uuid-from-previous-response", "name": "My QR Code", "size": 300, "foreground_color": "#000000", "background_color": "#FFFFFF" }'
Need Help?
Explore our comprehensive guides and examples to get the most out of the Cutly API.
Need help? Our support team is here to assist you with any questions or issues.
Getting Help
Email Support
Get detailed help via email
support@cutly.com
Response within 24 hours
Live Chat
Instant help from our Chatbot
Available 24/7
Pro+ users only
Documentation
Comprehensive guides and examples
Always Available
Self-service help
Can't find what you're looking for? Contact our support team