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

# Introduction

> Integrate H0p into your apps and workflows

The H0p API gives you full programmatic control over your short links, custom domains, QR codes, and analytics. Automate link creation from your CMS, pull click data into your dashboards, or let AI agents manage your campaigns through a clean RESTful interface.

## What you can build

<CardGroup cols={2}>
  <Card title="Marketing automation" icon="bullhorn">
    Create campaign-specific links automatically from your marketing tools.
  </Card>

  <Card title="CMS integration" icon="newspaper">
    Generate short links when content is published.
  </Card>

  <Card title="Analytics dashboards" icon="chart-mixed">
    Pull click data into your BI tools for custom reporting.
  </Card>

  <Card title="AI workflows" icon="robot">
    Let AI agents create and manage links via MCP.
  </Card>
</CardGroup>

## API capabilities

| Feature            | Description                                                                   |
| ------------------ | ----------------------------------------------------------------------------- |
| **Short links**    | Create, update, delete links with custom slugs, routing rules, and protection |
| **Custom domains** | Add and verify your own domains for branded links                             |
| **QR codes**       | Generate customizable QR codes with logos and branding                        |
| **Analytics**      | Access click data by geography, device, browser, and UTM parameters           |
| **Folders & tags** | Organize links programmatically                                               |
| **Webhooks**       | Receive real-time notifications for events                                    |
| **Files**          | Upload images for QR codes and social previews                                |

## Getting started

<Steps>
  <Step title="Create an API key">
    Generate an API key from the [H0p dashboard](https://dashboard.h0p.co) under **Developer Tools** > **API Keys**.
  </Step>

  <Step title="Make your first request">
    Test your key by listing your domains or creating a short link.
  </Step>

  <Step title="Build your integration">
    Connect H0p to your tools using our REST endpoints or MCP server.
  </Step>
</Steps>

<Note>
  Ready to start? Follow the [Quickstart guide](/api-reference/quickstart) to make your first API call.
</Note>

## Authentication

All API requests require an API key in the `x-api-key` header:

```bash theme={null}
curl -X GET "https://api.h0p.co/short-link/list?page=0&limit=10" \
  -H "x-api-key: YOUR_API_KEY"
```

API keys are scoped to a specific organization and have configurable permissions. See the [Authentication guide](/api-reference/authentication) for details on key types and permissions.

<Warning>
  Keep your API key secure. Never expose it in client-side code or public repositories.
</Warning>

## Base URL

All API requests should be made to:

```
https://api.h0p.co
```

## API documentation

The H0p API is documented using OpenAPI 3.0. You can:

* Browse the [interactive API reference](/api-reference/quickstart) in this documentation
* Access the OpenAPI spec directly at `https://api.h0p.co/doc`
* View the Swagger UI at `https://api.h0p.co/ui`

## Request format

All `POST`, `PATCH`, and `PUT` requests must include a JSON body with the `Content-Type: application/json` header.

```bash theme={null}
curl -X POST "https://api.h0p.co/short-link" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": {
      "type": "link",
      "value": "https://example.com"
    },
    "slug": "my-link"
  }'
```

## Response format

Successful responses return JSON with the requested data:

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "my-link",
  "shortUrl": "https://h0p.co/my-link",
  "destination": {
    "type": "link",
    "value": "https://example.com"
  },
  "clicks": 0,
  "createdAt": "2024-01-15T10:30:00.000Z"
}
```

Error responses include a code and message:

```json theme={null}
{
  "error": {
    "code": "ALREADY_EXIST",
    "message": "A link with this slug already exists"
  }
}
```

## HTTP status codes

| Code  | Description                                                |
| ----- | ---------------------------------------------------------- |
| `200` | Success - Request completed                                |
| `201` | Created - Resource created successfully                    |
| `400` | Bad Request - Invalid parameters or request body           |
| `401` | Unauthorized - Invalid or missing API key                  |
| `403` | Forbidden - Insufficient permissions or plan limit reached |
| `404` | Not Found - Resource doesn't exist                         |
| `409` | Conflict - Resource already exists (e.g., duplicate slug)  |
| `429` | Too Many Requests - Rate limit exceeded                    |
| `500` | Server Error - Something went wrong on our end             |

### Common error codes

| Code                    | Description                                    |
| ----------------------- | ---------------------------------------------- |
| `UNAUTHORIZED`          | Invalid or missing API key                     |
| `FORBIDDEN`             | You don't have permission for this action      |
| `NOT_FOUND`             | The requested resource doesn't exist           |
| `ALREADY_EXIST`         | A resource with this identifier already exists |
| `PLAN_LIMIT_REACHED`    | Your plan limit has been exceeded              |
| `FEATURE_NOT_AVAILABLE` | This feature requires a Premium subscription   |
| `ACTION_NOT_ALLOWED`    | Your API key doesn't have this permission      |
| `VALIDATION_ERROR`      | Request body validation failed                 |

## Rate limiting

API requests are rate-limited to ensure fair usage:

| Limit               | Value |
| ------------------- | ----- |
| Requests per second | 5     |
| Requests per minute | 100   |

When you exceed the rate limit, you receive a `429 Too Many Requests` response:

```json theme={null}
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please retry later."
  }
}
```

Implement exponential backoff in your integration:

```javascript theme={null}
async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.status !== 429) {
      return response;
    }

    const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
    await new Promise(resolve => setTimeout(resolve, delay));
  }

  throw new Error('Max retries exceeded');
}
```

## Pagination

List endpoints support pagination with `page` and `limit` parameters:

```bash theme={null}
curl "https://api.h0p.co/short-link/list?page=0&limit=20" \
  -H "x-api-key: YOUR_API_KEY"
```

Response includes pagination metadata:

```json theme={null}
{
  "items": [...],
  "pagination": {
    "page": 0,
    "limit": 20,
    "totalItems": 150,
    "totalPages": 8
  }
}
```

* `page` starts at 0
* `limit` defaults to 10, maximum 50

## SDKs and tools

While we don't offer official SDKs yet, you can:

* Use the OpenAPI spec to generate clients in any language
* Connect via MCP for AI tool integration
* Use standard HTTP libraries in your preferred language

## Support

<CardGroup cols={2}>
  <Card title="Contact support" icon="envelope" href="mailto:contact@h0p.co">
    Reach out for technical assistance.
  </Card>

  <Card title="Dashboard" icon="gauge" href="https://dashboard.h0p.co">
    Manage your links, domains, and API keys.
  </Card>
</CardGroup>