Creating Links

Overview

The Bouncy.ai API offers multiple ways to create short links:

Single link creation - Create one link at a time with full customization
Bulk creation - Create up to 100 links in a single request
Custom slugs - Choose your own memorable short URLs
Tags and groups - Organize links for campaigns

Create a Simple Link

The minimum required field is url - the destination URL:

curl -X POST https://api.bouncy.ai/v1/links \
  -H "Authorization: Bearer bcy_live_pk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/my-page"
  }'

const link = await fetch('https://api.bouncy.ai/v1/links', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer bcy_live_pk_YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://example.com/my-page'
  })
}).then(res => res.json());

console.log(link.shortUrl); // https://bouncy.ai/abc123

import requests

response = requests.post(
    'https://api.bouncy.ai/v1/links',
    headers={
        'Authorization': 'Bearer bcy_live_pk_YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={'url': 'https://example.com/my-page'}
)

link = response.json()
print(link['shortUrl'])  # https://bouncy.ai/abc123

Response:

{
  "id": "link_abc123",
  "shortUrl": "https://bouncy.ai/abc123",
  "slug": "abc123",
  "destination": "https://example.com/my-page",
  "createdAt": "2026-02-06T12:00:00Z",
  "enabled": true,
  "clicks": 0
}

The API automatically generates a random slug (abc123) if you don’t specify one.

Create a Customized Link

Add optional fields for full control:

{
  "url": "https://example.com/summer-sale",
  "slug": "summer",                    // Custom short URL
  "title": "Summer Sale 2026",         // For SEO
  "description": "50% off everything", // For social cards
  "tags": ["marketing", "sale"],       // Organize your links
  "domain": "go.yourbrand.com"         // Custom domain (if configured)
}

Full example:

curl -X POST https://api.bouncy.ai/v1/links \
  -H "Authorization: Bearer bcy_live_pk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/summer-sale",
    "slug": "summer",
    "title": "Summer Sale 2026",
    "description": "50% off everything",
    "tags": ["marketing", "sale"]
  }'

const link = await fetch('https://api.bouncy.ai/v1/links', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer bcy_live_pk_YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://example.com/summer-sale',
    slug: 'summer',
    title: 'Summer Sale 2026',
    description: '50% off everything',
    tags: ['marketing', 'sale']
  })
}).then(res => res.json());

Slug Best Practices

Keep slugs short and memorable

✅ Good: summer, promo, docs
❌ Bad: this-is-a-very-long-slug-that-nobody-will-remember

Use lowercase letters, numbers, and hyphens

✅ Valid: summer-2026, promo123, new-product
❌ Invalid: Summer Sale!, promo@2026, new_product

Check for slug conflicts

If a slug is already taken, you’ll receive a 409 Conflict error:

{
  "error": {
    "code": "slug_already_exists",
    "message": "The slug 'summer' is already in use"
  }
}

Solution: Choose a different slug or omit the slug field for auto-generation.

Using Custom Domains

If you’ve connected a custom domain (e.g., go.yourbrand.com), specify it in the domain field:

{
  "url": "https://example.com/page",
  "slug": "welcome",
  "domain": "go.yourbrand.com"
}

This creates: https://go.yourbrand.com/welcome

Custom domains must be verified before use. See the Custom Domains guide for setup instructions.

Organizing with Tags

Tags help you filter and organize links:

{
  "url": "https://example.com/instagram-post",
  "slug": "ig-jan",
  "tags": ["instagram", "january", "client-abc"]
}

Later, retrieve all links with a specific tag:

GET /v1/links?tag=instagram

Organizing with Groups

Groups provide folder-like organization:

Create a group

curl -X POST https://api.bouncy.ai/v1/groups \
  -H "Authorization: Bearer bcy_live_pk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Summer Campaign"}'

Response: {"id": "grp_abc123", "name": "Summer Campaign"}

Assign links to the group

curl -X PATCH https://api.bouncy.ai/v1/groups/grp_abc123/links \
  -H "Authorization: Bearer bcy_live_pk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"linkIds": ["link_123", "link_456"]}'

See the Groups API Reference for more details.

Error Handling

Common errors when creating links:

Invalid URL

{
  "error": {
    "code": "invalid_url",
    "message": "The URL must be a valid HTTP or HTTPS URL",
    "field": "url"
  }
}

Solution: Ensure your URL starts with http:// or https://.

Slug Already Exists

{
  "error": {
    "code": "slug_already_exists",
    "message": "The slug 'summer' is already in use"
  }
}

Solution: Choose a different slug or omit it for auto-generation.

Link Quota Exceeded

{
  "error": {
    "code": "quota_exceeded",
    "message": "You've reached your plan's link limit",
    "currentPlan": "growth",
    "currentLinks": 1000,
    "maxLinks": 1000
  }
}

Solution: Upgrade your plan or delete unused links.

Next Steps

Bulk Create Links

Create up to 100 links at once

Update Links

Modify link destinations and metadata

Get Analytics

Track clicks and performance

Error Handling

Handle errors gracefully

Get Started

Guides

Overview

Create a Simple Link

Create a Customized Link

Slug Best Practices

Using Custom Domains

Organizing with Tags

Organizing with Groups

Error Handling

Invalid URL

Slug Already Exists

Link Quota Exceeded

Next Steps

Bulk Create Links

Update Links

Get Analytics

Error Handling

​Overview

​Create a Simple Link

​Create a Customized Link

​Slug Best Practices

​Using Custom Domains

​Organizing with Tags

​Organizing with Groups

​Error Handling

​Invalid URL

​Slug Already Exists

​Link Quota Exceeded

​Next Steps

Bulk Create Links

Update Links

Get Analytics

Error Handling

Overview

Create a Simple Link

Create a Customized Link

Slug Best Practices

Using Custom Domains

Organizing with Tags

Organizing with Groups

Error Handling

Invalid URL

Slug Already Exists

Link Quota Exceeded

Next Steps