REST API · JSON

Shortaty API documentation

Create and manage your short links programmatically from any application, service, or script — the same capabilities you get in the dashboard, exposed through a simple, predictable REST API.

🚀Get started in 30 seconds

Create a new key from the API Keys page.
Save the Secret — it's shown only once.
Send your first POST request to create your first link.

Base URL

https://short-tool.vercel.app/api/v1

All requests must use HTTPS. . HTTP requests are rejected.

Authentication

Every request must carry a valid API Key and Secret. There are two equivalent ways — pick whichever fits your HTTP client:

1. Dual-header (recommended)

Clearest and most common in API integrations.

curl https://short-tool.vercel.app/api/v1/links \
  -H "X-API-Key: pk_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

2. Bearer + Key (for tools that prefer the Authorization header)

Compatible with Postman, Insomnia, most SDKs.

curl https://short-tool.vercel.app/api/v1/links \
  -H "X-API-Key: pk_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Security

Never embed the Secret in browser-shipped code or public git. Use it only from your server or a proxy/backend.

Response Envelope

All responses follow the same unified envelope. That simplifies error handling in your code.

✓ Success

{
  "data": {
    "id": "abc-123",
    "short_url": "https://ostazna.blog/x7K9p2",
    ...
  }
}

✗ Error

{
  "error": {
    "code": "validation_failed",
    "message": "Invalid target URL"
  }
}

All responses include the header X-Api-Version: v1. . The status code (200 / 201 / 4xx / 5xx) conveys HTTP-level state, and the error.code field conveys the programmatic detail.

Scopes

Each key is provisioned with specific scopes at creation time. If you call an endpoint without the required scope, the response is 403 insufficient_scope.

Scope	Allows	Default?
links:read	Read links and basic stats	✓ Default
links:write	Create and edit links	✓ Default
links:delete	Permanently delete links	Optional
domains:read	List available domains	✓ Default
clicks:read	Read detailed click logs	Optional

The least privilegeprinciple: grant the key only what it needs. The links:delete and clicks:read scopes are non-default by design.

Rate limits & quotas

Active keys per account10

Request body size≤ 100 KB

Slug length1–200 chars

Password length1–200 chars

Title length≤ 200 chars

Per-URL length≤ 2 KB

Currently there's no strict requests-per-minute rate limit — but abuse may auto-disable the key. If you need higher limits, contact the admin.

Endpoints — overview

Method	Path	Scope
POST	/api/v1/links	links:write
GET	/api/v1/links	links:read
GET	/api/v1/links/:id	links:read
PATCH	/api/v1/links/:id	links:write
DELETE	/api/v1/links/:id	links:delete
GET	/api/v1/domains	domains:read

POST/api/v1/linksscope: links:write

Creates a new link on a domain available to your account. Auto-generates a slug if you don't provide one.

Body parameters

name	type	Required	Description
target_url	string	✓	Target URL. Must be http/https. Unsafe URLs are rejected.
domain	string	✓	Domain hostname (e.g. ostazna.blog).
slug	string (1–200)	—	If omitted, auto-generated (6 chars).
subdomain	string \| null	—	A valid subdomain label (a–z, 0–9, hyphen).
title	string (≤200)	—	Internal title for identification in the dashboard.
password	string	—	Prompts for a password before redirecting.
expires_at	ISO datetime	—	Expiration timestamp (ISO 8601).
max_clicks	integer > 0	—	Maximum allowed clicks.
target_rules	object	—	{ mobile?: url, tablet?: url, desktop?: url }

curl -X POST https://short-tool.vercel.app/api/v1/links \
  -H "X-API-Key: pk_..." \
  -H "X-API-Secret: sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "target_url": "https://example.com/very/long/url",
    "domain": "ostazna.blog",
    "title": "Spring sale",
    "expires_at": "2026-06-01T00:00:00Z"
  }'

Response (201)

{
  "data": {
    "id":          "8b3b6e8c-7e9a-4b1f-bb87-1e0c1f4f5b3e",
    "short_url":   "https://ostazna.blog/x7K9p2",
    "slug":        "x7K9p2",
    "subdomain":   null,
    "domain":      "ostazna.blog",
    "target_url":  "https://example.com/very/long/url",
    "title":       "Spring sale",
    "expires_at":  "2026-06-01T00:00:00.000Z",
    "max_clicks":  null,
    "is_active":   true,
    "created_at":  "2026-05-21T10:30:00.000Z"
  }
}

GET/api/v1/linksscope: links:read

Returns your links with pagination.

Query parameters

name	type	Required	Description
limit	integer 1–100	—	default: 50
offset	integer ≥ 0	—	default: 0

curl "https://short-tool.vercel.app/api/v1/links?limit=20&offset=0" \
  -H "X-API-Key: pk_..." \
  -H "X-API-Secret: sk_..."

Response

{
  "data": {
    "links": [
      {
        "id":          "8b3b6e8c-...",
        "short_url":   "https://ostazna.blog/x7K9p2",
        "slug":        "x7K9p2",
        "subdomain":   null,
        "domain":      "ostazna.blog",
        "target_url":  "https://example.com/long/url",
        "title":       "Spring sale",
        "click_count": 42,
        "expires_at":  null,
        "max_clicks":  null,
        "is_active":   true,
        "created_at":  "2026-05-21T10:30:00.000Z"
      }
    ],
    "pagination": { "total": 137, "limit": 20, "offset": 0 }
  }
}

GET/api/v1/links/:idscope: links:read

Returns a single link with full details, including target_rules.

curl https://short-tool.vercel.app/api/v1/links/8b3b6e8c-7e9a-4b1f-bb87-1e0c1f4f5b3e \
  -H "X-API-Key: pk_..." \
  -H "X-API-Secret: sk_..."

PATCH/api/v1/links/:idscope: links:write

Partial update — send only the fields you want to change. Every field is optional, but you must send at least one.

Body parameters

name	type	Required	Description
target_url	string	—	New target URL.
title	string \| null	—	null to clear the field.
is_active	boolean	—	true/false to enable or disable.
expires_at	ISO \| null	—	null to remove the expiration.
max_clicks	integer \| null	—	null to remove the limit.
password	string \| null	—	null to remove the password.
target_rules	object \| null	—	{ mobile?, tablet?, desktop? }

curl -X PATCH https://short-tool.vercel.app/api/v1/links/8b3b6e8c-... \
  -H "X-API-Key: pk_..." \
  -H "X-API-Secret: sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false, "title": "Paused — pending review" }'

DELETE/api/v1/links/:idscope: links:delete

Delete is permanent — every click record attached to the link is deleted with it. If you only want to disable the redirect without losing data, use PATCH with is_active: false.

curl -X DELETE https://short-tool.vercel.app/api/v1/links/8b3b6e8c-... \
  -H "X-API-Key: pk_..." \
  -H "X-API-Secret: sk_..."

GET/api/v1/domainsscope: domains:read

Returns the domains you can create links on. Admins — all domains. Regular users — only granted domains.

curl https://short-tool.vercel.app/api/v1/domains \
  -H "X-API-Key: pk_..." \
  -H "X-API-Secret: sk_..."

Error codes

Status	code	Meaning
400	invalid_body	Body isn't valid JSON.
401	missing_credentials	X-API-Key or X-API-Secret is missing.
401	invalid_key	api_key not found.
401	invalid_secret	Secret doesn't match the key.
401	revoked_key	The key was revoked.
401	expired_key	The key has expired.
403	insufficient_scope	The key lacks the required scope.
403	forbidden	Not your link.
403	domain_not_granted	You aren't granted access to this domain.
403	domain_disabled	The domain is disabled for your account.
404	not_found	Resource not found.
404	domain_not_found	Domain isn't registered.
409	slug_taken	The slug is already used on this domain.
422	validation_failed	A body field is invalid (see message).
422	invalid_slug	Slug contains illegal chars or is reserved.
422	invalid_subdomain	Subdomain is invalid or reserved.
422	domain_not_verified	Domain hasn't been verified yet.
422	nothing_to_update	PATCH without any field.
500	insert_failed	Unexpected DB failure.
500	slug_generation_failed	Couldn't generate a unique slug.

Ready to start?

Create your first key in under a minute and start creating links programmatically.

Create API Key