Complete Developer Guide to the Alias URL Shortener API
· Developers · 7 min read
A practical guide to the Alias REST API: authentication, creating short links, managing links, handling responses, and using the official TypeScript SDK.
The Alias API lets you create, manage, and retrieve short links programmatically. Whether you're building a marketing automation workflow, integrating short links into your application, or generating links in bulk for a campaign, the REST API gives you full control.
Getting Your API Key
All API requests require an API key for authentication. To get one, log in to your Alias dashboard, go to Settings → API Keys, and generate a new key. Store it securely — treat it like a password. Pass it as a Bearer token in the Authorization header of every request.
Base URL and Versioning
The current API version is v1. All endpoints are prefixed with https://alias.live/api/v1. The API returns JSON for all responses, including errors.
Creating a Short Link
Send a POST request to /api/v1/links with a JSON body containing the target URL and optional settings:
- url (required): The destination URL to shorten.
- slug (optional): A custom alias for the short link. If omitted, a random slug is generated.
- expiresAt (optional): ISO 8601 datetime after which the link stops redirecting.
- password (optional): A password visitors must enter before being redirected.
The response includes the full short link URL, the slug, the creation timestamp, and the click count (initially zero).
Retrieving Your Links
GET /api/v1/links returns all links for the authenticated account, sorted by creation date descending. The response includes click counts, creation dates, expiry dates, and the original URLs. Use this endpoint to build dashboards, sync data to your CRM, or audit your active links.
Updating and Deleting Links
PATCH /api/v1/links/:slug updates a link's destination URL, expiry date, or password. DELETE /api/v1/links/:slug permanently removes a link. Deleted links return a 404 to anyone who tries to visit them.
Using the TypeScript SDK
The official Alias TypeScript SDK provides a typed wrapper around the REST API. Install it from npm with: npm install @alias-app/sdk. Initialize it with your API key and call methods like alias.links.create(), alias.links.list(), and alias.links.delete(). The SDK handles authentication, request serialization, and error parsing automatically.
Bulk Link Creation
For campaigns that require hundreds or thousands of short links, the Alias API supports bulk creation. POST an array of link objects to /api/v1/links/bulk and receive all the created short links in a single response. This is significantly faster than sequential single-link requests.
Error Handling
- 400 Bad Request: The request body is invalid or missing required fields.
- 401 Unauthorized: The API key is missing, expired, or incorrect.
- 409 Conflict: The requested custom slug is already taken.
- 429 Too Many Requests: You have hit the rate limit. Wait before retrying.
- 500 Internal Server Error: A server-side error occurred. Retry with exponential backoff.
Rate Limits
The Alias API applies rate limiting per API key. Standard accounts can make up to 1,000 requests per hour. For higher limits, contact support. The response headers include X-RateLimit-Remaining and X-RateLimit-Reset to help you manage request pacing.