> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bouncy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating Links

> Learn how to create short links with the Bouncy.ai API

## 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:

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript JavaScript theme={null}
  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
  ```

  ```python Python theme={null}
  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
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "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:

```javascript theme={null}
{
  "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:

<CodeGroup>
  ```bash cURL theme={null}
  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"]
    }'
  ```

  ```javascript JavaScript theme={null}
  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());
  ```
</CodeGroup>

## Slug Best Practices

<AccordionGroup>
  <Accordion title="Keep slugs short and memorable">
    * ✅ Good: `summer`, `promo`, `docs`
    * ❌ Bad: `this-is-a-very-long-slug-that-nobody-will-remember`
  </Accordion>

  <Accordion title="Use lowercase letters, numbers, and hyphens">
    * ✅ Valid: `summer-2026`, `promo123`, `new-product`
    * ❌ Invalid: `Summer Sale!`, `promo@2026`, `new_product`
  </Accordion>

  <Accordion title="Check for slug conflicts">
    If a slug is already taken, you'll receive a `409 Conflict` error:

    ```json theme={null}
    {
      "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.
  </Accordion>
</AccordionGroup>

## Using Custom Domains

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

```javascript theme={null}
{
  "url": "https://example.com/page",
  "slug": "welcome",
  "domain": "go.yourbrand.com"
}
```

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

<Note>
  Custom domains must be verified before use. See the [Custom Domains guide](#) for setup instructions.
</Note>

## Organizing with Tags

Tags help you filter and organize links:

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

Later, retrieve all links with a specific tag:

```bash theme={null}
GET /v1/links?tag=instagram
```

## Organizing with Groups

Groups provide folder-like organization:

<Steps>
  <Step title="Create a group">
    ```bash theme={null}
    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"}`
  </Step>

  <Step title="Assign links to the group">
    ```bash theme={null}
    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"]}'
    ```
  </Step>
</Steps>

See the [Groups API Reference](/api-reference/groups/create-group) for more details.

## Error Handling

Common errors when creating links:

### Invalid URL

```json theme={null}
{
  "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

```json theme={null}
{
  "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

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

**Solution**: [Upgrade your plan](https://bouncy.ai/pricing) or delete unused links.

## Next Steps

<CardGroup cols={2}>
  <Card title="Bulk Create Links" icon="layer-group" href="/api-reference/links/bulk-create">
    Create up to 100 links at once
  </Card>

  <Card title="Update Links" icon="pen" href="/api-reference/links/update-link">
    Modify link destinations and metadata
  </Card>

  <Card title="Get Analytics" icon="chart-line" href="/api-reference/analytics/get-link-analytics">
    Track clicks and performance
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/guides/error-handling">
    Handle errors gracefully
  </Card>
</CardGroup>