Create Link

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 response = 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']
  })
});

const { data: link } = await response.json();
console.log(link.url);

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/summer-sale',
        'slug': 'summer',
        'title': 'Summer Sale 2026',
        'description': '50% off everything',
        'tags': ['marketing', 'sale']
    }
)

link = response.json()['data']
print(link['url'])

{
  "success": true,
  "data": {
    "id": "summer",
    "url": "https://bouncy.ai/summer",
    "slug": "summer",
    "destination": "https://example.com/summer-sale",
    "domain": "bouncy.ai",
    "title": "Summer Sale 2026",
    "description": "50% off everything",
    "tags": ["marketing", "sale"],
    "isActive": true,
    "createdAt": "2026-02-06T12:00:00Z"
  }
}

{
  "error": "Missing custom slug"
}

{
  "error": "Custom slug or domain already taken"
}

POST

links

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 response = 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']
  })
});

const { data: link } = await response.json();
console.log(link.url);

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/summer-sale',
        'slug': 'summer',
        'title': 'Summer Sale 2026',
        'description': '50% off everything',
        'tags': ['marketing', 'sale']
    }
)

link = response.json()['data']
print(link['url'])

{
  "success": true,
  "data": {
    "id": "summer",
    "url": "https://bouncy.ai/summer",
    "slug": "summer",
    "destination": "https://example.com/summer-sale",
    "domain": "bouncy.ai",
    "title": "Summer Sale 2026",
    "description": "50% off everything",
    "tags": ["marketing", "sale"],
    "isActive": true,
    "createdAt": "2026-02-06T12:00:00Z"
  }
}

{
  "error": "Missing custom slug"
}

{
  "error": "Custom slug or domain already taken"
}

Request

Headers

string

required

Must be application/json

Body

string

required

The destination URL where the short link should redirect. Must be a valid HTTP or HTTPS URL.Example: https://example.com/my-page

string

required

Custom slug for the short URL. Must be unique and contain only lowercase letters, numbers, and hyphens.Example: summer-sale

string

Title for SEO and social media sharingExample: Summer Sale 2026

string

Description for SEO and social media cardsExample: Get 50% off all products this summer

array

Array of tags for organizing linksExample: ["marketing", "summer", "instagram"]

string

Domain to use for the short URL. Can be a system domain (e.g., bouncy.link, mybouncy.link) or a custom domain verified in your account.Example: bouncy.ai Default: bouncy.ai

string

ID of the group to add this link toExample: grp_abc123

array

Array of geographic filtering rules. Rules are evaluated in order and the first matching rule wins. Visitors who match no rule are redirected to the main destination url.Each rule is an object with:

countries (array) - ISO 3166-1 alpha-2 codes (e.g., US, GB) or full country names
presetId (string) - ID of a saved geo preset, as returned by GET /v1/geo-presets. Use this in place of countries: the server fills the rule’s countries from the preset’s saved country list when the link is saved. An unknown presetId returns a 400 error
cities (array) - City names, matched as case-insensitive substrings. Can be combined with either countries or presetId
redirectUrl (string) - Destination URL for visitors matching this rule. Always required, including when the rule uses presetId

Preset countries are copied into the rule at save time. Editing the preset later does not change links it was already applied to.Example:

[
  {
    "countries": ["US", "GB"],
    "cities": ["Manchester"],
    "redirectUrl": "https://example.com/uk-us-landing"
  },
  {
    "presetId": "a1B2c3D4e5F6g7H8",
    "redirectUrl": "https://example.com/preset-landing"
  }
]

array

Array of language-based filtering rules

Response

boolean

Whether the operation succeeded

object

The created link object

Show properties

string

Unique identifier for the link

string

The complete short URL

string

The slug portion of the short URL

string

The destination URL

string

Domain used for the short URL

string

Link title

string

Link description

array

Array of tags

boolean

Whether the link is active

string

ISO 8601 timestamp of creation

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 response = 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']
  })
});

const { data: link } = await response.json();
console.log(link.url);

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/summer-sale',
        'slug': 'summer',
        'title': 'Summer Sale 2026',
        'description': '50% off everything',
        'tags': ['marketing', 'sale']
    }
)

link = response.json()['data']
print(link['url'])

{
  "success": true,
  "data": {
    "id": "summer",
    "url": "https://bouncy.ai/summer",
    "slug": "summer",
    "destination": "https://example.com/summer-sale",
    "domain": "bouncy.ai",
    "title": "Summer Sale 2026",
    "description": "50% off everything",
    "tags": ["marketing", "sale"],
    "isActive": true,
    "createdAt": "2026-02-06T12:00:00Z"
  }
}

{
  "error": "Missing custom slug"
}

{
  "error": "Custom slug or domain already taken"
}

Links

Geo Presets

Analytics

Groups

Domains

Websites

Account

Request

Headers

Body

Response

​Request

​Headers

​Body

​Response

Request

Headers

Body

Response