Introduction

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

Marketing automation

Create campaign-specific links automatically from your marketing tools.

CMS integration

Generate short links when content is published.

Analytics dashboards

Pull click data into your BI tools for custom reporting.

AI workflows

Let AI agents create and manage links via MCP.

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

Create an API key

Generate an API key from the H0p dashboard under Developer Tools > API Keys.

Make your first request

Test your key by listing your domains or creating a short link.

Build your integration

Connect H0p to your tools using our REST endpoints or MCP server.

Ready to start? Follow the Quickstart guide to make your first API call.

Authentication

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

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 for details on key types and permissions.

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

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

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:

{
  "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:

{
  "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:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please retry later."
  }
}

Implement exponential backoff in your integration:

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:

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

Response includes pagination metadata:

{
  "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

Contact support

Reach out for technical assistance.

Dashboard

Manage your links, domains, and API keys.

Getting Started

Endpoints

Introduction

What you can build

Marketing automation

CMS integration

Analytics dashboards

AI workflows

API capabilities

Getting started

Authentication

Base URL

API documentation

Request format

Response format

HTTP status codes

Common error codes

Rate limiting

SDKs and tools

Support

Contact support

Dashboard

​What you can build

Marketing automation

CMS integration

Analytics dashboards

AI workflows

​API capabilities

​Getting started

​Authentication

​Base URL

​API documentation

​Request format

​Response format

​HTTP status codes

​Common error codes

​Rate limiting

​Pagination

​SDKs and tools

​Support

Contact support

Dashboard

What you can build

API capabilities

Getting started

Authentication

Base URL

API documentation

Request format

Response format

HTTP status codes

Common error codes

Rate limiting

Pagination

SDKs and tools

Support