API Documentation

HidURL API Reference

Integrate URL shortening into your applications with our simple REST API.

Authentication

All API requests require authentication using a Bearer token. Include it in the Authorization header:

Authorization: Bearer your_api_token

Get your API token from the API Keys dashboard. All users can create API tokens.

Base URL

https://api.hidurl.com/v1

All API endpoints are prefixed with this base URL.

Rate Limits

When you exceed your plan's rate limit, the API returns a 429 Too Many Requests response with a retry_after field indicating when you can retry. Per-minute and daily limits vary by plan - see the pricing page for the full breakdown.

Endpoints

POST

/shorten

Create a shortened URL

Request Body

{
  "url": "string (required)",
  "alias": "string (optional, alphanumeric - min length by plan: Free=6, Starter/Pro/Bulk=5, Enterprise=4)",
  "tags": "string (optional, Starter+) - comma-separated, up to 5 tags, 50 chars each"
}

Example

curl -X POST https://api.hidurl.com/v1/shorten \
  -H "Authorization: Bearer your_api_token" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/very-long-url"}'

Response

// HTTP 201 Created
{
  "data": {
    "short_url": "https://hidurl.com/abc123",
    "short_code": "abc123",
    "original_url": "https://example.com/very-long-url",
    "tags": [],
    "created_at": "2025-01-28T12:00:00.000000Z"
  }
}

POST

/shorten

with custom alias

Create a shortened URL with a custom alias

Example

curl -X POST https://api.hidurl.com/v1/shorten \
  -H "Authorization: Bearer your_api_token" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/page", "alias": "mylink"}'

Response

// HTTP 201 Created
{
  "data": {
    "short_url": "https://hidurl.com/mylink",
    "short_code": "mylink",
    "original_url": "https://example.com/page",
    "created_at": "2025-01-28T12:00:00.000000Z"
  }
}

POST

/bulk

Create multiple shortened URLs at once (Bulk plan required)

Request Body

{
  "urls": [
    { "url": "https://example1.com" },
    { "url": "https://example2.com", "alias": "ex2link" }
  ]
}

Example

curl -X POST https://api.hidurl.com/v1/bulk \
  -H "Authorization: Bearer your_api_token" \
  -H "Content-Type: application/json" \
  -d '{"urls": [{"url": "https://example1.com"}, {"url": "https://example2.com"}]}'

Response

// HTTP 201 Created
{
  "data": [
    {
      "short_url": "https://hidurl.com/xk92pq",
      "short_code": "xk92pq",
      "original_url": "https://example1.com"
    },
    {
      "short_url": "https://hidurl.com/ex2link",
      "short_code": "ex2link",
      "original_url": "https://example2.com"
    }
  ]
}

GET

/urls/{code}

Get information about a shortened URL

Example

curl https://api.hidurl.com/v1/urls/abc123 \
  -H "Authorization: Bearer your_api_token"

Response

// HTTP 200 OK
{
  "data": {
    "short_url": "https://hidurl.com/abc123",
    "short_code": "abc123",
    "original_url": "https://example.com/very-long-url",
    "clicks": 42,
    "is_active": true,
    "tags": ["marketing", "promo"],
    "created_at": "2025-01-28T12:00:00.000000Z"
  }
}

PATCH

/urls/{code}

Update a link. url and is_active require Starter+. alias and expires_at require Pro+. tags requires Starter+.

Request Body

{
  "url": "string (optional) - new destination URL",
  "alias": "string (optional) - rename the short code / alias",
  "is_active": "boolean (optional) - enable or disable the link",
  "expires_at": "string|null (optional) - ISO 8601 date, or null to clear expiry",
  "tags": "string (optional, Starter+) - comma-separated, up to 5 tags, 50 chars each"
}

Example

curl -X PATCH https://api.hidurl.com/v1/urls/abc123 \
  -H "Authorization: Bearer your_api_token" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://new-destination.com", "alias": "new-alias", "is_active": true, "expires_at": "2026-12-31"}'

Response

// HTTP 200 OK
{
  "data": {
    "short_url": "https://hidurl.com/new-alias",
    "short_code": "new-alias",
    "original_url": "https://new-destination.com",
    "is_active": true,
    "expires_at": "2026-12-31T00:00:00.000000Z",
    "tags": ["work"]
  }
}
// Plan restrictions (HTTP 403) if your plan doesn't support that field

GET

/urls/{code}/stats

Get detailed statistics for a URL (Pro plan required)

Example

curl https://api.hidurl.com/v1/urls/abc123/stats \
  -H "Authorization: Bearer your_api_token"

Response

// HTTP 200 OK
{
  "data": {
    "short_url": "https://hidurl.com/abc123",
    "short_code": "abc123",
    "original_url": "https://example.com/very-long-url",
    "total_clicks": 1234,
    "device_stats": [
      { "device_type": "desktop", "count": 800 },
      { "device_type": "mobile", "count": 400 },
      { "device_type": "tablet", "count": 34 }
    ],
    "browser_stats": [
      { "browser": "Chrome", "count": 600 },
      { "browser": "Safari", "count": 400 }
    ],
    "os_stats": [
      { "os": "Windows", "count": 500 },
      { "os": "macOS", "count": 400 }
    ]
  }
}

DELETE

/urls/{code}

Delete a shortened URL

Example

curl -X DELETE https://api.hidurl.com/v1/urls/abc123 \
  -H "Authorization: Bearer your_api_token"

Response

// HTTP 200 OK
{
  "message": "URL deleted successfully"
}

Error Codes

Code	Description
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Feature not available on your plan
`404`	Not Found - URL not found
`429`	Too Many Requests - Rate limit exceeded

Ready to get started?

Create your API key and start integrating in minutes.