Skip to main content
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

FeatureDescription
Short linksCreate, update, delete links with custom slugs, routing rules, and protection
Custom domainsAdd and verify your own domains for branded links
QR codesGenerate customizable QR codes with logos and branding
AnalyticsAccess click data by geography, device, browser, and UTM parameters
Folders & tagsOrganize links programmatically
WebhooksReceive real-time notifications for events
FilesUpload images for QR codes and social previews

​
Getting started

1

Create an API key

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

Make your first request

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

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

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

​
Common error codes

CodeDescription
UNAUTHORIZEDInvalid or missing API key
FORBIDDENYou don’t have permission for this action
NOT_FOUNDThe requested resource doesn’t exist
ALREADY_EXISTA resource with this identifier already exists
PLAN_LIMIT_REACHEDYour plan limit has been exceeded
FEATURE_NOT_AVAILABLEThis feature requires a Premium subscription
ACTION_NOT_ALLOWEDYour API key doesn’t have this permission
VALIDATION_ERRORRequest body validation failed

​
Rate limiting

API requests are rate-limited to ensure fair usage:
LimitValue
Requests per second5
Requests per minute100
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.