toui.io API

Quickstart

Install the SDK and shorten your first link in under a minute. Prefer raw HTTP? Use the curl tab — every endpoint works in any language.

npm install toui-js

curl -X POST https://toui.io/api/v1/shorten \
  -H "Authorization: Bearer toui_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/a-very-long-link"}'

import { Toui } from 'toui-js';

const toui = new Toui({ apiKey: process.env.TOUI_API_KEY! });

const { short_url } = await toui.shorten({ url: 'https://example.com/a-very-long-link' });
console.log(short_url); // https://toui.io/aBcD3f

You need an API key first — see Authentication.

Use toui from your AI tools

toui runs a remote MCP server at https://mcp.toui.io — shorten links without leaving Claude, ChatGPT, Cursor, Cline, or any MCP-capable agent. No API key needed; it uses OAuth.

Cursor — one click

Or add it manually to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "toui": { "url": "https://mcp.toui.io" }
  }
}

Cline, Claude, ChatGPT, and other agents: paste https://mcp.toui.io as a custom MCP/connector. See the setup guide.

toui is also listed on Smithery, the MCP server registry.

Authentication

All requests authenticate with a Bearer token. Create an API key in your dashboard → API Keys, then send it in the Authorization header:

Authorization: Bearer toui_YOUR_API_KEY

Keys are shown once at creation. Treat them like passwords — never embed them in client-side code. The base URL for every endpoint is https://toui.io/api/v1.

Shorten a URL

POST /api/v1/shorten

Creates a short link. Only url is required. custom_code is available on paid plans; the Open Graph fields (og_title, og_description, og_image_url) are available on every plan and control the social-share preview.

curl -X POST https://toui.io/api/v1/shorten \
  -H "Authorization: Bearer toui_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/long",
    "custom_code": "promo",
    "title": "Spring sale",
    "og_title": "Spring sale",
    "og_description": "Up to 50% off",
    "og_image_url": "https://example.com/banner.png"
  }'

const url = await toui.shorten({
  url: 'https://example.com/long',
  custom_code: 'promo',        // paid plans only
  title: 'Spring sale',
  og_title: 'Spring sale',
  og_description: 'Up to 50% off',
  og_image_url: 'https://example.com/banner.png',
});

Response · 201 Created

{
  "short_url": "https://toui.io/aBcD3f",
  "short_code": "aBcD3f",
  "target_url": "https://example.com/long",
  "created_at": "2026-06-04T08:00:00.000Z"
}

Get a URL

GET /api/v1/urls/:code

Returns metadata and the lifetime click count for a short code you own. Returns 404 if the code does not exist in your team.

curl https://toui.io/api/v1/urls/aBcD3f \
  -H "Authorization: Bearer toui_YOUR_API_KEY"

const url = await toui.get('aBcD3f');
console.log(url.click_count, url.target_url);

Response · 200 OK

{
  "short_code": "aBcD3f",
  "target_url": "https://example.com/long",
  "title": "Spring sale",
  "click_count": 42,
  "created_at": "2026-06-04T08:00:00.000Z",
  "is_active": true,
  "og_title": null,
  "og_description": null,
  "og_image_url": null
}

Get stats

GET /api/v1/urls/:code/stats?days=30

Returns daily clicks and a country breakdown. The days window is capped by your plan's retention (Free 30, Pro 90, Business 365 days). Paid plans (with advanced analytics) also receive referrer and device breakdowns in the same response.

curl "https://toui.io/api/v1/urls/aBcD3f/stats?days=30" \
  -H "Authorization: Bearer toui_YOUR_API_KEY"

const stats = await toui.stats('aBcD3f', { days: 30 });
console.log(stats.total_clicks);
for (const day of stats.daily) {
  console.log(day.date, day.clicks, day.unique_visitors);
}

Response · 200 OK

{
  "short_code": "aBcD3f",
  "target_url": "https://example.com/long",
  "total_clicks": 128,
  "daily": [
    { "date": "2026-06-01", "clicks": 5, "unique_visitors": 4 }
  ],
  "countries": [
    { "country": "TW", "clicks": 80 }
  ]
}

SDK (toui-js)

toui-js is the official TypeScript SDK — zero dependencies, native fetch, works in Node 18+, Bun, Deno, Cloudflare Workers, and browsers. Source on GitHub, published on npm.

npm install toui-js

Construct a client with new Toui({ apiKey, baseUrl?, fetch? }), then call shorten(), get(), or stats(). Errors throw a TouiError carrying the HTTP status:

import { Toui, TouiError } from 'toui-js';

try {
  await toui.shorten({ url: 'not-a-url' });
} catch (err) {
  if (err instanceof TouiError) {
    console.error(err.status, err.message); // 400 …
  }
}

Errors

Errors return a JSON body with an error message and a standard HTTP status. Rate-limit responses add fields describing the limit.

Rate limits

Two layers apply: a per-minute burst limit and monthly/daily quotas. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. New free accounts are throttled for the first 48 hours.

A 429 burst response includes retry_after (seconds); quota responses include resets_at (ISO timestamp).