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

# Create Link

> Create a new short link with optional customization

## Request

### Headers

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`
</ParamField>

### Body

<ParamField body="url" type="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`
</ParamField>

<ParamField body="slug" type="string" required>
  Custom slug for the short URL. Must be unique and contain only lowercase letters, numbers, and hyphens.

  **Example:** `summer-sale`
</ParamField>

<ParamField body="title" type="string">
  Title for SEO and social media sharing

  **Example:** `Summer Sale 2026`
</ParamField>

<ParamField body="description" type="string">
  Description for SEO and social media cards

  **Example:** `Get 50% off all products this summer`
</ParamField>

<ParamField body="tags" type="array">
  Array of tags for organizing links

  **Example:** `["marketing", "summer", "instagram"]`
</ParamField>

<ParamField body="domain" type="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`
</ParamField>

<ParamField body="groupId" type="string">
  ID of the group to add this link to

  **Example:** `grp_abc123`
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Whether the operation succeeded
</ResponseField>

<ResponseField name="data" type="object">
  The created link object

  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique identifier for the link
    </ResponseField>

    <ResponseField name="url" type="string">
      The complete short URL
    </ResponseField>

    <ResponseField name="slug" type="string">
      The slug portion of the short URL
    </ResponseField>

    <ResponseField name="destination" type="string">
      The destination URL
    </ResponseField>

    <ResponseField name="domain" type="string">
      Domain used for the short URL
    </ResponseField>

    <ResponseField name="title" type="string">
      Link title
    </ResponseField>

    <ResponseField name="description" type="string">
      Link description
    </ResponseField>

    <ResponseField name="tags" type="array">
      Array of tags
    </ResponseField>

    <ResponseField name="isActive" type="boolean">
      Whether the link is active
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp of creation
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```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 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);
  ```

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

  link = response.json()['data']
  print(link['url'])
  ```
</RequestExample>

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

  ```json 400 Bad Request theme={null}
  {
    "error": "Missing custom slug"
  }
  ```

  ```json 400 Slug Taken theme={null}
  {
    "error": "Custom slug or domain already taken"
  }
  ```
</ResponseExample>