URL Shortener API

The TinyTo REST API: create short links, read their stats and manage them from your own code.

v1 REST · JSON Base URL: https://tinyto.me/api Advanced plan Open as Markdown ↗

Overview

Every request is JSON over HTTPS. Responses always use the same envelope: on success data holds the payload and error is null; on failure data is null and the HTTP status plus error.code tell you what happened.

The API is scoped to the account that owns the key. You cannot read or modify links from another account, and there is no endpoint that returns data across accounts.

Availability: the API is included in the Advanced plan. If the account drops to a lower plan, existing keys stop working immediately with 403 forbidden.

Quickstart

Create a key. Open Dashboard → API, give it a name and copy it. It is shown once; we store only a hash.
Check it works. GET /v1/me is the cheapest call and returns your plan and link usage.
Create your first link and keep the id: every other endpoint keys off it.

curl https://tinyto.me/api/v1/me \
  -H "Authorization: Bearer tto_live_..."

const res = await fetch("https://tinyto.me/api/v1/me", {
  headers: { Authorization: `Bearer ${process.env.TINYTO_KEY}` },
});
console.log(await res.json());

import os, requests

res = requests.get(
    "https://tinyto.me/api/v1/me",
    headers={"Authorization": f"Bearer {os.environ['TINYTO_KEY']}"},
    timeout=10,
)
print(res.json())

A healthy response looks like this:

{
  "data": {
    "plan": "advanced",
    "link_usage": { "used": 42, "limit": null, "unlimited": true },
    "key_scope": "write"
  },
  "error": null
}

Authentication

Send the key as a bearer token. X-API-Key is accepted as an alias when a tool cannot set an Authorization header.

Authorization: Bearer tto_live_9fJ2k...
# or
X-API-Key: tto_live_9fJ2k...

Property	Behaviour
Format	`tto_live_` followed by 43 base64url characters
Storage	Only a SHA-256 hash and a 16-character prefix are kept
Scopes	`read` or `write`; write implies read
Expiry	30, 90 or 365 days, or never
Revocation	Immediate, on the next request
Limit	10 active keys per account

Keys are secrets. Keep them out of client-side code and version control; rotate by creating a new key and revoking the old one.

Conventions

Topic	Rule
Content type	Requests with a body must send `Content-Type: application/json`
Timestamps	ISO 8601 in UTC, e.g. `2026-10-30T09:14:02.000Z`
Identifiers	UUIDs. Pass the `id`, never the slug
Pagination	`limit` (max 100) and `offset`, plus a `pagination` object
Caching	Responses are `no-store`; do not cache
Idempotency	Creating two links with the same body creates two links; use a unique slug if you need to detect duplicates

Endpoints

Six endpoints. read keys can call every GET; write keys are required for POST and DELETE.

POST /v1/links write scope

Create a link

Creates a short link owned by the key's account. Counts against the plan's active-link allowance.

Field	In	Type	Required	Notes
`url`	body	string	yes	Destination. `http`/`https` is assumed if the scheme is missing. Max 2048 chars.
`slug`	body	string	no	Custom path, 3–50 alphanumeric characters. Must be free across the whole service.
`expires_at`	body	string	no	ISO 8601 timestamp in the future. The link stops resolving after it.

curl -X POST https://tinyto.me/api/v1/links \
  -H "Authorization: Bearer tto_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/spring-sale",
    "slug": "spring-sale"
  }'

const res = await fetch("https://tinyto.me/api/v1/links", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TINYTO_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com/spring-sale",
    slug: "spring-sale",
  }),
});

const { data, error } = await res.json();
if (error) throw new Error(error.message);
console.log(data.short_url);

import os, requests

res = requests.post(
    "https://tinyto.me/api/v1/links",
    headers={"Authorization": f"Bearer {os.environ['TINYTO_KEY']}"},
    json={
        "url": "https://example.com/spring-sale",
        "slug": "spring-sale",
    },
    timeout=10,
)
res.raise_for_status()
print(res.json()["data"]["short_url"])

Response · 201 Created

{
  "data": {
    "id": "9f1c8b7a-2d4e-4a11-9b0c-3f7f2c1d8e44",
    "short_url": "https://tinyto.me/spring-sale",
    "stats_url": "https://tinyto.me/spring-sale/stats",
    "url": "https://example.com/spring-sale",
    "slug": "spring-sale",
    "expires_at": null
  },
  "error": null
}

GET /v1/links read scope

List links

Returns the account's links, newest first.

Field	In	Type	Required	Notes
`limit`	query	integer	no	Page size, 1–100. Default 50.
`offset`	query	integer	no	How many links to skip. Default 0.

curl "https://tinyto.me/api/v1/links?limit=20&offset=0" \
  -H "Authorization: Bearer tto_live_..."

const res = await fetch("https://tinyto.me/api/v1/links?limit=20", {
  headers: { Authorization: `Bearer ${process.env.TINYTO_KEY}` },
});

const { data } = await res.json();
data.items.forEach((link) => console.log(link.short_url, link.clicks));

res = requests.get(
    "https://tinyto.me/api/v1/links",
    params={"limit": 20},
    headers={"Authorization": f"Bearer {os.environ['TINYTO_KEY']}"},
    timeout=10,
)
for link in res.json()["data"]["items"]:
    print(link["short_url"], link["clicks"])

Response · 200 OK

{
  "data": {
    "items": [
      {
        "id": "9f1c8b7a-...",
        "short_url": "https://tinyto.me/spring-sale",
        "url": "https://example.com/spring-sale",
        "clicks": 128,
        "created_at": "2026-10-30T09:14:02.000Z"
      }
    ],
    "pagination": {
      "total": 42,
      "limit": 20,
      "offset": 0,
      "has_more": true
    }
  },
  "error": null
}

GET /v1/links/:id read scope

Get a link

Returns one link owned by the account.

Field	In	Type	Required	Notes
`id`	path	string	yes	The link `id` returned at creation, not the slug.

curl https://tinyto.me/api/v1/links/9f1c8b7a-... \
  -H "Authorization: Bearer tto_live_..."

const res = await fetch(
  `https://tinyto.me/api/v1/links/${id}`,
  { headers: { Authorization: `Bearer ${process.env.TINYTO_KEY}` } }
);

res = requests.get(
    f"https://tinyto.me/api/v1/links/{link_id}",
    headers={"Authorization": f"Bearer {os.environ['TINYTO_KEY']}"},
    timeout=10,
)

Response · 200 OK

{
  "data": {
    "id": "9f1c8b7a-...",
    "short_url": "https://tinyto.me/spring-sale",
    "url": "https://example.com/spring-sale",
    "slug": "spring-sale",
    "clicks": 128,
    "created_at": "2026-10-30T09:14:02.000Z",
    "expires_at": null,
    "password_protected": false
  },
  "error": null
}

DELETE /v1/links/:id write scope

Delete a link

Deletes the link and its stats. The short URL stops resolving immediately.

Field	In	Type	Required	Notes
`id`	path	string	yes	The link `id`.

curl -X DELETE https://tinyto.me/api/v1/links/9f1c8b7a-... \
  -H "Authorization: Bearer tto_live_..."

await fetch(`https://tinyto.me/api/v1/links/${id}`, {
  method: "DELETE",
  headers: { Authorization: `Bearer ${process.env.TINYTO_KEY}` },
});

requests.delete(
    f"https://tinyto.me/api/v1/links/{link_id}",
    headers={"Authorization": f"Bearer {os.environ['TINYTO_KEY']}"},
    timeout=10,
)

Response · 200 OK

{
  "data": { "deleted": true, "id": "9f1c8b7a-..." },
  "error": null
}

GET /v1/links/:id/stats read scope

Link stats

Click totals, top countries and the hour/weekday heatmap for one link. Bot traffic is excluded from the heatmap.

Field	In	Type	Required	Notes
`id`	path	string	yes	The link `id`.
`—`	—	—	—	No query parameters in v1.

curl https://tinyto.me/api/v1/links/9f1c8b7a-.../stats \
  -H "Authorization: Bearer tto_live_..."

const res = await fetch(
  `https://tinyto.me/api/v1/links/${id}/stats`,
  { headers: { Authorization: `Bearer ${process.env.TINYTO_KEY}` } }
);

const { data } = await res.json();
console.log(data.total_clicks, data.countries);

res = requests.get(
    f"https://tinyto.me/api/v1/links/{link_id}/stats",
    headers={"Authorization": f"Bearer {os.environ['TINYTO_KEY']}"},
    timeout=10,
)
data = res.json()["data"]
print(data["total_clicks"], data["countries"])

Response · 200 OK

{
  "data": {
    "id": "9f1c8b7a-...",
    "short_url": "https://tinyto.me/spring-sale",
    "total_clicks": 128,
    "countries": [
      { "country": "ES", "clicks": 74 },
      { "country": "MX", "clicks": 21 },
      { "country": "FR", "clicks": 12 }
    ],
    "heatmap": [
      { "hour": 9, "dayOfWeek": 1, "clicks": 14 },
      { "hour": 20, "dayOfWeek": 3, "clicks": 12 }
    ],
    "heatmap_shape": "hour is 0-23, day_of_week is 0 (Sunday) to 6 (Saturday)"
  },
  "error": null
}

GET /v1/me read scope

Account and key

Confirms the key works and returns the plan, link usage and the key's own scope.

Field	In	Type	Required	Notes
`—`	—	—	—	No parameters.

curl https://tinyto.me/api/v1/me \
  -H "Authorization: Bearer tto_live_..."

const res = await fetch("https://tinyto.me/api/v1/me", {
  headers: { Authorization: `Bearer ${process.env.TINYTO_KEY}` },
});

res = requests.get(
    "https://tinyto.me/api/v1/me",
    headers={"Authorization": f"Bearer {os.environ['TINYTO_KEY']}"},
    timeout=10,
)

Response · 200 OK

{
  "data": {
    "plan": "advanced",
    "link_usage": { "used": 42, "limit": null, "unlimited": true },
    "key_scope": "write"
  },
  "error": null
}

MCP server

The same account is reachable over the Model Context Protocol, so Claude and ChatGPT can create and read links as a tool rather than through raw HTTP. The endpoint is https://tinyto.me/mcp.

Authentication is OAuth 2.1 with PKCE. The client registers itself, sends the user through a consent screen and receives a bearer token — there is no API key to paste. Unlike the REST API, the MCP server is available on every plan; link limits follow the plan.

Tool	Scope	What it does
`list_links`	links:read	List links with click counts, newest first
`get_link`	links:read	One link with its destination and clicks
`get_link_stats`	links:read	Clicks, countries and the weekday/hour heatmap
`account_info`	links:read	Plan, active links and remaining allowance
`create_link`	links:create	Shorten a URL, optionally with a slug or expiry

No tool deletes or edits an existing link: the assistant can create and read, nothing else. create_link is the only write operation and is marked non-destructive, so clients show it without extra warnings.

Connecting a client

Every client takes the same URL and walks the OAuth flow from there: Claude, Claude Code, ChatGPT, OpenCode, Cursor, VS Code, Codex CLI, Gemini CLI, Windsurf, Zed, Cline and Antigravity. Step-by-step instructions, including the exact config for each one, live on their own page:

Connect TinyTo to Claude, ChatGPT and other MCP clients →

Discovery endpoints

Clients discover everything from these, so no manual configuration is needed:

URL	Purpose
`/.well-known/oauth-protected-resource`	RFC 9728 metadata: which authorization server protects `/mcp`
`/.well-known/oauth-authorization-server`	RFC 8414 metadata: authorize, token, registration and JWKS URLs
`/.well-known/jwks.json`	Public keys to verify access tokens

Access tokens are RS256 JWTs with the audience set to https://tinyto.me/mcp, valid for one hour, refreshed with a rotating refresh token. Users disconnect an app from Dashboard → API, which invalidates its tokens immediately; clients can also call POST /oauth/revoke (RFC 7009).

Errors

Failures never throw a different shape. Treat error.code as the stable contract and the HTTP status as a hint.

{
  "data": null,
  "error": {
    "code": "invalid_request",
    "message": "slug must be 3-50 alphanumeric characters."
  }
}

Status	Code	When
`400`	`invalid_request`	A required field is missing, has the wrong type, or the slug/expiry is invalid.
`401`	`unauthorized`	No key, or the key is invalid, expired or revoked.
`402`	`plan_limit_reached`	The account has no active links left on its plan.
`403`	`forbidden`	Read-only key used for a write call, or the plan does not include API access.
`404`	`not_found`	The link does not exist, or it belongs to another account.
`429`	`rate_limited`	More than 120 requests in a minute for this key.
`500`	`server_error`	Unexpected failure on our side. Safe to retry with backoff.

Rate limits

120 requests per minute per key, counted in a rolling window. Exceeding it returns 429 with Retry-After and the X-RateLimit-* headers.

HTTP/1.1 429 Too Many Requests
Retry-After: 17
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1793352680

Back off on Retry-After rather than retrying immediately, and batch reads where you can.

Changelog

Date	Change
2026-10-30	v1 published: links, per-link stats and account endpoints.

Machine-readable contract: /openapi.json, generated from the same list this page renders. Breaking changes will ship under /v2; v1 keeps working for at least 6 months after a successor is announced.

Create a key