Skip to Content
API Reference

API Reference

The Redirectly API allows you to programmatically create and manage dynamic links. This API is available for paid subscription users only.

Base URL

https://redirectly.app/api/v2/links

Authentication

All API requests require Bearer token authentication. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

You can find your API key in your Redirectly dashboard .

Prerequisites

Before using the API, ensure:

  1. Active Subscription - You must have an active or trialing subscription
  2. Username/Subdomain Setup - Your username/subdomain must be configured in your profile
  3. API Key - You need a valid API key from your dashboard 

Retrieve all links for your account.

Request

curl -X GET https://redirectly.app/api/v2/links \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

Returns an array of links with click counts:

[
  {
    "id": "uuid",
    "slug": "my-link",
    "target": "https://example.com/page",
    "user_id": "uuid",
    "created_at": "2024-01-01T00:00:00Z",
    "click_count": 42,
    "url": "https://yourusername.redirectly.app/my-link",
    "custom_params": {
      "param1": "value1",
      "param2": "value2"
    }
  }
]

Response Fields

  • id - Unique link identifier
  • slug - Link slug/identifier
  • target - Target URL (may be null if using custom_params only)
  • user_id - Your user ID
  • created_at - Link creation timestamp
  • click_count - Total number of clicks
  • url - Full clickable Redirectly URL
  • custom_params - Custom parameters object (key-value pairs)

Error Responses

401 Unauthorized

{
  "error": "Unauthorized"
}

Invalid or missing API key.

400 Bad Request

{
  "error": "Username/subdomain not set up. Please set up your username in your profile before creating links."
}

Username/subdomain not configured in your profile.

POST /api/v2/links

Create a new dynamic link.

Request

curl -X POST https://redirectly.app/api/v2/links \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "my-link",
    "target": "https://example.com/page",
    "custom_params": {
      "campaign": "summer-sale",
      "source": "email"
    }
  }'

Request Body

{
  "slug": "string (required)",
  "target": "string (optional)",
  "custom_params": {
    "key1": "value1",
    "key2": "value2"
  }
}

Request Parameters

slug (required)

  • Type: String
  • Format: Alphanumeric characters, hyphens, and underscores only
  • Example: "my-link", "product_123", "campaign-2024"
  • Validation: Must match pattern /^[a-zA-Z0-9_-]+$/

target (optional, deprecated in v2)

  • Type: String (URL)
  • Description: Target URL to redirect to
  • Note: In v2, target is optional. You can use custom_params instead or in combination with target

custom_params (optional)

  • Type: Object
  • Description: Custom key-value parameters for advanced routing
  • Constraints:
    • Maximum 10 key-value pairs
    • Keys must be non-empty strings
    • Values must be strings
    • Object structure only (not arrays)
  • Example: 
    {
  "campaign": "summer-sale",
  "source": "email",
  "user_id": "12345"
}

Important: At least one of target or custom_params must be provided.

Response

{
  "id": "uuid",
  "slug": "my-link",
  "target": "https://example.com/page",
  "user_id": "uuid",
  "created_at": "2024-01-01T00:00:00Z",
  "click_count": 0,
  "url": "https://yourusername.redirectly.app/my-link",
  "custom_params": {
    "campaign": "summer-sale",
    "source": "email"
  }
}

Error Responses

401 Unauthorized

{
  "error": "Unauthorized"
}

Invalid or missing API key.

400 Bad Request

Missing slug:

{
  "error": "Slug is required"
}

Invalid slug format:

{
  "error": "Slug can only contain letters, numbers, hyphens, and underscores"
}

Missing target and custom_params:

{
  "error": "At least one of target URL or custom_params is required"
}

Invalid target URL:

{
  "error": "Invalid target URL"
}

Invalid custom_params:

{
  "error": "custom_params must be an object"
}
{
  "error": "custom_params cannot have more than 10 key-value pairs"
}
{
  "error": "custom_params keys must be non-empty strings"
}
{
  "error": "custom_params value for key \"campaign\" must be a string"
}

Username not set up:

{
  "error": "Username/subdomain not set up. Please set up your username in your profile before creating links."
}

403 Forbidden

{
  "error": "Your subscription is not active. Please update your billing information or start a trial."
}

Subscription is not active or trialing.

409 Conflict

{
  "error": "Slug already exists"
}

The slug is already in use. Choose a different slug.

Examples

curl -X POST https://redirectly.app/api/v2/links \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "welcome",
    "target": "https://myapp.com/welcome"
  }'
curl -X POST https://redirectly.app/api/v2/links \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "summer-sale",
    "target": "https://myapp.com/sale",
    "custom_params": {
      "campaign": "summer-2024",
      "source": "email",
      "discount": "20"
    }
  }'
curl -X POST https://redirectly.app/api/v2/links \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "campaign-tracker",
    "custom_params": {
      "campaign_id": "12345",
      "user_segment": "premium"
    }
  }'
curl -X GET https://redirectly.app/api/v2/links \
  -H "Authorization: Bearer YOUR_API_KEY"

Rate Limits

Rate limits apply to prevent abuse. If you exceed the rate limit, you’ll receive a 429 Too Many Requests response.

Subscription Requirements

This API endpoint requires an active paid subscription (Pro plan or higher). Free tier users cannot access this API.

To upgrade your subscription:

  1. Visit your Redirectly dashboard 
  2. Navigate to Billing settings
  3. Upgrade to a Pro plan

Best Practices

  1. Use Meaningful Slugs - Choose descriptive slugs that reflect the link’s purpose
  2. Validate URLs - Ensure target URLs are valid before making API calls
  3. Handle Errors - Implement proper error handling for all API responses
  4. Store API Keys Securely - Never expose your API key in client-side code
  5. Use Custom Params Wisely - Keep custom_params under 10 key-value pairs
  6. Check Subscription Status - Verify your subscription is active before making requests
Last updated on
Features