API Documentation

URLZone API Documentation

Base URL: https://api.urlzone.in

Open Interactive API Reference Manage API Keys

Getting Started

The URLZone API lets you create and list short links programmatically. Every request is made against the base URL above and authenticated with an API key.

  1. Sign in to your URLZone account.
  2. Open API Keys and create a new key. The full key is shown once — copy it immediately.
  3. Send it as a bearer token on every request (see Authentication).
  4. Call POST /create to shorten a URL, or GET /urls to list your links.
The current public API surface is intentionally small: creating and listing your own short links. More endpoints may be added over time.

Authentication

The preferred way to authenticate is an API key, sent as a bearer token:

Header
Authorization: Bearer uz_live_YOUR_API_KEY

API keys are created from the API Key management page in your dashboard. Each key belongs to your account and can be scoped, revoked, and re-created independently.

Example request

cURL
curl -X POST "https://api.urlzone.in/create" \
  -H "Authorization: Bearer uz_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com"
  }'
Keep your API key secret.
  • Never commit it to source control.
  • Never expose it in frontend or browser-side code.
  • The full key is shown only once, immediately after creation — store it in a secrets manager or environment variable.
  • If a key may have leaked, revoke it from the API Key page and create a new one.

List URLs

GET /urls
API key required Scope: links:read

Returns a paged list of the short links owned by your account.

Request

cURL
curl "https://api.urlzone.in/urls?pageNumber=1&pageSize=10" \
  -H "Authorization: Bearer uz_live_YOUR_KEY"

pageNumber (optional, default 1) and pageSize (optional, default 10, max 50) control pagination.

Response — 200 OK

JSON
[
  {
    "longUrl": "https://example.com",
    "shortUrl": "https://urlzone.in/u/abc123",
    "code": "abc123",
    "createdDate": "2026-01-15T10:22:00Z",
    "isActive": true,
    "expiresAt": null
  }
]

Pagination metadata (total count, page size, current page, total pages, whether a next/previous page exists) is returned in the X-Pagination response header as JSON.

Common errors

StatusMeaning
401Missing or invalid API key.
403The key is missing the links:read scope, or the account's current plan doesn't include API access.
429Rate limit exceeded.

Errors

Every endpoint uses standard HTTP status codes. The statuses relevant to authentication and rate limiting are:

StatusWhat it means
401 Unauthorized Authentication is missing or invalid — no API key was sent, or it's malformed, unknown, revoked, or expired.
403 Forbidden The authenticated caller doesn't have permission — a missing scope, or the account's plan doesn't include the required entitlement.
429 Too Many Requests Rate limit exceeded. Respect the Retry-After header and retry after that interval.

Rate Limits

API requests are rate limited to keep the platform reliable for everyone. If you send requests too quickly, you'll receive a 429 Too Many Requests response.

HEADER Retry-After: <seconds>

When present, wait for the number of seconds given in Retry-After before retrying. We recommend backing off and retrying rather than immediately re-sending the request.

Exact limits are not published here and may change; build your integration to handle 429 gracefully rather than assuming a fixed request budget.

Legacy API Deprecated

Existing integrations may still authenticate with a JWT plus the legacy x-uz-token header. This method remains supported temporarily for backward compatibility and is not recommended for new integrations.

Legacy headers (deprecated)
Authorization: Bearer YOUR_JWT
x-uz-token: YOUR_LEGACY_TOKEN

Use API-key authentication (above) for all new integrations. Legacy JWT + x-uz-token support has not been removed and continues to work, but it will not receive new capabilities.