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.

Core Features
  • • URL shortening with custom aliases
  • • QR code generation and customization
  • • Custom domain management
  • • Click analytics and tracking
  • • Team member management
  • • Password-protected links
Security
  • • 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

  1. Log into your Cutly dashboard
  2. Navigate to the APIs section
  3. Click "Create API Key"
  4. Give your key a descriptive name
  5. Copy the generated key (it's only shown once)

Permissions

Only users with Owner or Admin roles can create and manage API keys.

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.

PlanRequests/MinuteRequests/Day
Free601,000
Starter30010,000
Pro1,000100,000
Business5,0001,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.

Short Links
Create, manage, and track shortened URLs
POST /api/v1/short-links

Create

GET /api/v1/short-links

List

PUT /api/short-links/[id]

Update

DELETE /api/short-links/[id]

Delete

QR Codes
Generate and customize QR codes for your links
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

Custom Domains
Manage custom domains for branded short URLs
GET /api/custom-domains

List

POST /api/custom-domains

Create

DELETE /api/custom-domains

Delete

Analytics
Access click analytics and usage data
GET /api/click-analytics

Click Data

GET /api/api-usage

API Usage

GET /api/qr-analytics

API Usage

GET /api/page-analytics

API Usage

Team Management
Manage team members and invitations
GET /api/team-members

List

POST /api/team-members/invite

Invite

DELETE /api/team-members/[id]

Remove

API Keys
Manage your API keys and access tokens
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 CodeDescriptionCommon Causes

200

SuccessRequest completed successfully

201

CreatedResource created successfully

400

Bad RequestInvalid request data or missing required fields

401

UnauthorizedMissing or invalid API key

403

ForbiddenInsufficient permissions

404

Not FoundResource doesn't exist

409

ConflictResource already exists (e.g., duplicate alias)

429

Too Many RequestsRate limit exceeded

500

Internal Server ErrorServer 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"
  }'

Next Steps

Ready to dive deeper? Check out our detailed endpoint documentation and examples:

Need Help?

Documentation

Explore our comprehensive guides and examples to get the most out of the Cutly API.

Support

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

API Reference | Documentation