TinyURL APItinyurl.com ↗
Create tinyurl.com short links programmatically. Returns short URL, alias, destination, hash, and creation/expiry timestamps via a single POST endpoint.
What is the TinyURL API?
The TinyURL API exposes 1 endpoint — short_url — that creates a shortened tinyurl.com link for any absolute HTTP or HTTPS destination URL and returns 7 fields including the full short_url, the alias path segment, the original long_url, and ISO-8601 created_at and expires_at timestamps. Custom aliases between 5 and 30 characters are supported, or TinyURL assigns a random one when omitted.
curl -X POST 'https://api.parse.bot/scraper/872aa954-9d93-47b8-8d73-e8d53a0c5730/short_url' \
-H 'X-API-Key: $PARSE_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"url": "https://www.wikipedia.org/wiki/Portugal",
"alias": "lisbon-wiki-p7q2x9"
}'Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace tinyurl-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: TinyURL shortener SDK — create short links."""
from parse_apis.tinyurl_com_api import TinyUrl, InvalidInput
client = TinyUrl()
# Shorten a URL with a custom alias.
try:
link = client.links.create(
url="https://www.wikipedia.org/wiki/Portugal",
alias="portugal-wiki",
)
except InvalidInput as e:
# Alias already taken or invalid format.
print("Could not create link:", e.message)
else:
print(link.short_url) # https://tinyurl.com/portugal-wiki
print(link.long_url) # original destination
print(link.created_at) # ISO-8601 creation timestamp
print(link.expires_at) # None when the link never expires
# Shorten another URL, letting TinyURL assign a random alias.
random_link = client.links.create(url="https://www.example.com")
print(random_link.alias, random_link.domain)
print("exercised: links.create")
Creates a shortened tinyurl.com link for an absolute http(s) destination URL and returns the short URL together with its alias, domain, destination, internal hash and creation/expiry timestamps. When alias is omitted TinyURL assigns a random alias; when supplied it must be 5-30 characters (letters, digits, '-' or '_') and must not already be taken - an unavailable or rejected alias, or a destination URL the site refuses, yields a 422 stale_input whose message repeats the site's reason (e.g. 'alias: Alias is not available.'). Each call is a write on the site that mints a new public link; the same destination may be shortened again under a new alias. One call performs a fixed number of round trips (site state, human-verification token, creation) so latency is typically several seconds. QR-code image download links are not returned: tinyurl.com renders QR codes in the browser only and publishes no downloadable QR image URL for a link.
| Param | Type | Description |
|---|---|---|
| urlrequired | string | Absolute destination URL to shorten, including the http:// or https:// scheme. |
| alias | string | Custom alias for the short link (the path after tinyurl.com/), 5-30 characters using letters, digits, '-' or '_'. Omitted or empty = TinyURL generates a random alias. Aliases are globally unique on the site; a taken alias is rejected. |
{
"type": "object",
"fields": {
"hash": "site-internal identifier of the destination URL record",
"alias": "the path segment of the short URL, custom when supplied or site-generated otherwise",
"domain": "short-link domain, currently always tinyurl.com",
"long_url": "destination URL as stored by the site",
"short_url": "full shortened URL (https://tinyurl.com/<alias>)",
"created_at": "ISO-8601 creation timestamp of the alias",
"expires_at": "ISO-8601 expiry timestamp or null when the link does not expire",
"was_created": "boolean, true when the site created a new link record for this destination"
},
"sample": {
"data": {
"hash": "298yspy3",
"alias": "lisbon-wiki-p7q2x9",
"domain": "tinyurl.com",
"long_url": "https://www.wikipedia.org/wiki/Lisbon",
"short_url": "https://tinyurl.com/lisbon-wiki-p7q2x9",
"created_at": "2026-09-03T05:33:22+00:00",
"expires_at": null,
"was_created": true
},
"status": "success"
}
}About the TinyURL API
What the short_url endpoint returns
The short_url POST endpoint accepts a required url parameter (an absolute destination URL including scheme) and an optional alias parameter. It returns the complete shortened URL as short_url (e.g. https://tinyurl.com/<alias>), the alias path segment on its own, the domain (currently always tinyurl.com), and the long_url as stored by the site. It also returns a site-internal hash that identifies the destination URL record.
Aliases and creation behavior
When you supply an alias, it must be 5–30 characters using letters, digits, or hyphens. If the alias is already taken, the call will not create a new record. The boolean was_created field tells you whether the site created a new link during this request versus returning an existing one for the same destination. This is useful when checking idempotency — calling the endpoint twice for the same URL may return was_created: false on the second call.
Timestamps and expiry
created_at is an ISO-8601 timestamp marking when the alias record was created. expires_at is either an ISO-8601 expiry timestamp or null, indicating the link has no expiration. Most programmatically created links without an explicit expiry policy return null here.
The TinyURL API is a managed, monitored endpoint for tinyurl.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when tinyurl.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official tinyurl.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Shorten user-submitted URLs in a content management system and store the returned
short_urlfor display - Generate vanity links with a custom
aliasfor marketing campaigns and track thewas_createdflag to detect alias collisions - Archive the
hashandlong_urlfields alongside shortened links in a database for later reconciliation - Build a link-shortening microservice that exposes
expires_atso clients know when a link will stop resolving - Batch-shorten a list of destination URLs and record
created_attimestamps for audit logs - Validate that a custom alias was successfully reserved by checking
was_createdin the response
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does TinyURL have an official developer API?+
What does the `was_created` field tell me?+
was_created is true when the site created a brand-new alias record for your request, and false when it matched an existing record for the same destination URL. It lets you distinguish between first-time creation and a repeat call without doing a separate lookup.Can I look up or expand an existing short link to retrieve its destination?+
short_url endpoint and returns the long_url for the link you just created. It does not include a reverse-lookup or expansion endpoint for arbitrary tinyurl.com short links. You can fork this API on Parse and revise it to add a link-expansion endpoint.Are there any constraints on the `alias` parameter?+
alias parameter entirely, TinyURL assigns a random one and returns it in the alias field.Does the API return click analytics or redirect statistics for a short link?+
alias, short_url, long_url, hash, created_at, expires_at, and was_created — but no click counts or traffic data. You can fork this API on Parse and revise it to add an analytics endpoint if TinyURL exposes that data.