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

# Quickstart

> Start building with Bit2Connect API in under 5 minutes

## Setup your API Key

Get your API key from the Bit2Connect dashboard to start making API calls. You'll need an active subscription to access the API.

<Steps>
  <Step title="Create Account & Project">
    Sign up at [dash.bit2connect.com](https://dash.bit2connect.com) and create
    your first project. Each project gets its own API key for isolated link
    management.
  </Step>

  <Step title="Choose & Activate Subscription">
    Select our **Starter Plan** (\$29.99/month) to unlock unlimited dynamic links,
    advanced analytics, and full API access. This plan includes all core
    features for individual developers and small teams.
  </Step>

  <Step title="Navigate to API Settings">
    In your project dashboard, go to **Settings** → **API Keys** to manage your
    authentication credentials.
  </Step>

  <Step title="Generate API Key">
    Click **Generate New API Key** and copy the generated key. All Bit2Connect
    API keys start with `b2co_` prefix for easy identification.
  </Step>

  <Step title="Test Your Key">
    Use the key immediately - no activation required. Each key is tied to your
    project and subscription plan limits.
  </Step>
</Steps>

<Warning>
  **Security Best Practices**: Never expose API keys in client-side code, public
  repositories, or logs. Use environment variables in production and rotate keys
  regularly.
</Warning>

## API Rate Limits

The Bit2Connect API implements rate limiting to ensure fair usage and optimal performance:

<Info>**Current Rate Limit**: 180,000 requests per hour for all API keys</Info>

### Rate Limit Headers

Every API response includes rate limit information in the headers:

```bash theme={null}
X-RateLimit-Limit: 180000
X-RateLimit-Remaining: 179999
X-RateLimit-Reset: 2024-01-15T11:30:00.000Z
```

* `X-RateLimit-Limit`: Total requests allowed per hour (180000)
* `X-RateLimit-Remaining`: Requests remaining in current window
* `X-RateLimit-Reset`: ISO timestamp when the rate limit resets

### Handling Rate Limits

When you exceed your rate limit, you'll receive a `429 Too Many Requests` response:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "API rate limit exceeded. Please try again later."
  }
}
```

**Best Practices**:

* Monitor the rate limit headers in your responses
* Implement exponential backoff when approaching limits
* Cache responses when possible to reduce API calls
* Distribute requests evenly throughout the hour

<Warning>
  Rate limits are enforced per API key (180,000 requests/hour). The limit
  applies to all endpoints and resets every hour.
</Warning>

## API Endpoints & Authentication

The Bit2Connect Public API uses version 1.0 for external integrations:

<CodeGroup>
  ```bash Public API theme={null}
  # Base URL: https://api.bit2connect.com/1.0/
  # Authentication: X-API-KEY header
  curl -H "X-API-KEY: b2co_your_key_here" \
       https://api.bit2connect.com/1.0/links
  ```

  ```bash Example Request theme={null}
  curl -H "X-API-KEY: b2co_your_key_here" \
       -H "Content-Type: application/json" \
       https://api.bit2connect.com/1.0/links
  ```

  ```bash Headers Required theme={null}
  X-API-KEY: b2co_your_key_here
  Content-Type: application/json
  ```
</CodeGroup>

<Note>
  This documentation covers the **Public API (1.0)** for external integrations
  and third-party applications.
</Note>

## Make your first API call

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.bit2connect.com/1.0/links" \
    -H "X-API-KEY: b2co_your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Product 123 Link",
      "payload": {
        "link": "https://example.com/product/123",
        "android": {
          "package": "com.example.app",
          "store_fallback": "https://play.google.com/store/apps/details?id=com.example.app"
        },
        "ios": {
          "bundleId": "com.example.app",
          "app_store_fallback": "https://apps.apple.com/app/example-app/id123456789"
        },
        "social": {
          "title": "Check out this amazing product!",
          "description": "Discover the best deals on our mobile app",
          "image": "https://example.com/images/product-123.jpg"
        }
      },
      "expiresAt": "2025-01-15T10:30:00Z"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.bit2connect.com/1.0/links", {
    method: "POST",
    headers: {
      "X-API-KEY": "b2co_your_api_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Product 123 Link",
      payload: {
        link: "https://example.com/product/123",
        android: {
          package: "com.example.app",
          store_fallback:
            "https://play.google.com/store/apps/details?id=com.example.app",
        },
        ios: {
          bundleId: "com.example.app",
          app_store_fallback:
            "https://apps.apple.com/app/example-app/id123456789",
        },
        social: {
          title: "Check out this amazing product!",
          description: "Discover the best deals on our mobile app",
          image: "https://example.com/images/product-123.jpg",
        },
      },
    }),
  });

  const data = await response.json();
  console.log("Short URL:", data.data.shortUrl);
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.bit2connect.com/1.0/links"
  headers = {
      "X-API-KEY": "b2co_your_api_key_here",
      "Content-Type": "application/json"
  }

  payload = {
      "name": "Product 123 Link",
      "payload": {
          "link": "https://example.com/product/123",
          "android": {
              "package": "com.example.app",
              "store_fallback": "https://play.google.com/store/apps/details?id=com.example.app"
          },
          "ios": {
              "bundleId": "com.example.app",
              "app_store_fallback": "https://apps.apple.com/app/example-app/id123456789"
          },
          "social": {
              "title": "Check out this amazing product!",
              "description": "Discover the best deals on our mobile app",
              "image": "https://example.com/images/product-123.jpg"
          }
      }
  }

  response = requests.post(url, json=payload, headers=headers)
  data = response.json()
  print(f"Short URL: {data['data']['shortUrl']}")
  ```
</CodeGroup>

## Understanding the Response

A successful response will look like this:

```json theme={null}
{
  "success": true,
  "data": {
    "id": "clp123abc456",
    "code": "abc12345",
    "shortUrl": "https://b2co.link/abc12345",
    "originalUrl": "https://example.com/product/123",
    "name": "Product 123 Link",
    "status": "ACTIVE",
    "createdAt": "2024-01-15T10:30:00Z",
    "expiresAt": "2025-01-15T10:30:00Z",
    "clickCount": 0
  },
  "timestamp": "2024-01-15T10:30:00Z"
}
```

## Test Your Dynamic Link

Visit the `shortUrl` from different devices to see Bit2Connect's intelligent routing:

<Tabs>
  <Tab title="iOS Device">
    **With App Installed**: Opens directly in your app with deep link data
    **Without App**: Redirects to App Store, remembers intent for post-install
    deep linking
  </Tab>

  <Tab title="Android Device">
    **With App Installed**: Launches your Android app with deep link parameters
    **Without App**: Redirects to Play Store with install attribution tracking
  </Tab>

  <Tab title="Desktop Browser">
    **All Browsers**: Redirects to your website or specified desktop fallback
    URL **Social Crawlers**: Displays rich preview cards with your custom
    metadata
  </Tab>
</Tabs>

## Advanced Features

<CardGroup cols={2}>
  <Card title="Campaign Tracking" icon="chart-line">
    Add UTM parameters to track marketing campaign performance across channels.
  </Card>

  <Card title="A/B Testing" icon="flask">
    Create multiple links with different payloads to test user engagement and
    conversion rates.
  </Card>

  <Card title="Geographic Routing" icon="globe">
    Route users to different destinations based on their geographic location.
  </Card>

  <Card title="Time-based Links" icon="clock">
    Set expiration dates for time-sensitive campaigns and promotions.
  </Card>
</CardGroup>

<Tip>
  Monitor your usage with the `/usage` endpoint to avoid hitting rate limits
  during peak traffic.
</Tip>

## Next Steps

<CardGroup cols={2}>
  <Card title="Link Management" icon="link" href="/essentials/link-management">
    Understanding dynamic link creation, validation, and best practices
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Dive deep into our complete API documentation
  </Card>
</CardGroup>