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.

Feature Availability

Some fields - such as alias, domain, tags, and expires_at - are only available on certain plans. If your plan does not support a field, the API returns a 403 Forbidden response. Check the pricing page to see which features are included in your plan.

Endpoints

POST

/shorten

Create a shortened URL

Request Body

{
  "url": "string (required)",
  "alias": "string (optional) - custom short code, alphanumeric. Min length: 10 (Free), 5 (Starter/Pro/Business), 4 (Enterprise)",
  "domain": "string (optional) - hostname of a verified custom domain",
  "tags": "string (optional) - comma-separated list of tags"
}

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

/shorten

with branded domain

Pro+

Create a shortened URL on your own custom domain - requires a verified domain added in Settings → Domains

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/product-launch", "domain": "go.yourcompany.com"}'

Response

// HTTP 201 Created
{
  "data": {
    "short_url": "https://go.yourcompany.com/abc123",
    "short_code": "abc123",
    "original_url": "https://example.com/product-launch",
    "domain": "go.yourcompany.com",
    "tags": [],
    "created_at": "2025-01-28T12:00:00.000000Z"
  }
}

POST

/bulk

Submit a bulk shortening request. Returns a request_id immediately - processing happens asynchronously. Poll /status to track progress, then fetch /report for results. (Bulk plan required)

Request Body

{
  "urls": [
    { "url": "https://example1.com" },
    { "url": "https://example2.com", "alias": "ex2link", "domain": "go.yourcompany.com" },
    { "url": "https://example3.com", "alias": "launch", "domain": "go.yourcompany.com", "expires_at": "2026-12-31" }
  ]
}

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 (202 Accepted)

// HTTP 202 Accepted
{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "total": 2,
  "message": "Bulk request accepted and queued for processing."
}

GET

/bulk/{bulkRequestId}/status

Poll the processing status of a bulk request. Check processed vs total to track progress.

Example

curl https://api.hidurl.com/v1/bulk/{request_id}/status \
  -H "Authorization: Bearer your_api_token"

Response

// HTTP 200 OK
{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",  // pending | processing | completed | failed
  "total": 100,
  "processed": 47
}

GET

/bulk/{bulkRequestId}/report

Retrieve the full results once status is completed. Each item includes either the created short URL or an error message.

Example

curl https://api.hidurl.com/v1/bulk/{request_id}/report \
  -H "Authorization: Bearer your_api_token"

Response

// HTTP 200 OK
{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "total": 2,
  "processed": 2,
  "results": [
    {
      "original_url": "https://example1.com",
      "short_url": "https://hidurl.com/xk92pq",
      "short_code": "xk92pq",
      "domain": null,
      "expires_at": null
    },
    {
      "original_url": "https://example2.com",
      "error": "Alias 'ex2link' is already taken."
    }
  ]
}

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": 1,  // 0 = disabled by user, 1 = active, 2 = disabled by admin
    "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",
  "is_active": "0 | 1 (optional) - 0 = disable, 1 = enable. Cannot re-enable if disabled by admin (returns 403)",
  "expires_at": "string|null (optional) - ISO 8601 date, or null to clear expiry",
  "tags": "string (optional) - comma-separated list of tags"
}

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": 1, "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": 1,  // 0 = disabled by user, 1 = active, 2 = disabled by admin
    "expires_at": "2026-12-31T00:00:00.000000Z",
    "tags": ["work"]
  }
}
// HTTP 403 if your plan doesn't support that field, or if link is admin-disabled

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

POST

/unshorten

Resolve a shortened URL to its final destination by following all redirects

Example

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

Response

// HTTP 200 OK
{
  "data": {
    "original_url": "https://bit.ly/example",
    "final_url": "https://example.com/the-real-destination",
    "hops": [
      { "url": "https://bit.ly/example", "status": 301, "time_ms": 42 },
      { "url": "https://example.com/the-real-destination", "status": 200, "time_ms": 18 }
    ],
    "hop_count": 1,
    "total_time_ms": 60
  }
}

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.