Skip to main content

​
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
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"
  }'
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. 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"]
  }'

​
Slug Best Practices

  • ✅ Good: summer, promo, docs
  • ❌ Bad: this-is-a-very-long-slug-that-nobody-will-remember
  • ✅ Valid: summer-2026, promo123, new-product
  • ❌ Invalid: Summer Sale!, promo@2026, new_product
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:
1

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"}
2

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. 
{
  "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