Overview

The TinyZy REST API lets you create and manage short links, view analytics, and automate link workflows. All responses are JSON. All requests must be made over HTTPS.

Version: v1 · Format: JSON · Auth: Bearer token · HTTPS: required

Authentication

All link endpoints require an API key. Generate one from your account settings.

Pass your key in the Authorization header:
Authorization: Bearer tk_your_key_here

Or as a query parameter (less secure, useful for testing):
/api/v1/links?api_key=tk_your_key_here

Postman tip: In Postman's Auth tab, choose Bearer Token and enter only the token value (e.g. tk_abc123) — do not include the word "Bearer". Postman adds it automatically.

Example cURL with header

curl -X GET "https://tinyzy.com/api/v1/links" \
     -H "Authorization: Bearer tk_abc123..."

Error Codes

Standard HTTP status codes are used. All error responses include error: true and a message string.

Status	Meaning
200	OK — request succeeded
201	Created — resource created
400	Bad Request — missing or malformed parameters
401	Unauthorized — API key missing or invalid
403	Forbidden — you do not own this resource
404	Not Found — resource does not exist
409	Conflict — slug already in use
422	Unprocessable — validation failed
500	Server Error — something went wrong on our end

Error response shape

{
  "error":   true,
  "message": "Slug already in use"
}

Rate Limits

Limits are applied per API key, per minute. When exceeded, you receive a 429 Too Many Requests response.

Plan	Limit
Free	60 requests / minute
Pro	300 requests / minute
Business	1,000 requests / minute

GET /api/v1/links List all your short links

Returns a paginated list of all short links belonging to the authenticated user.

Query Parameters

Name	Type	Required	Description
page	integer	Optional	Page number, default `1`
per_page	integer	Optional	Items per page (1–100), default `20`

curl -X GET "https://tinyzy.com/api/v1/links?page=1&per_page=20" \
     -H "Authorization: Bearer tk_your_key"

<?php
$ctx = stream_context_create(['http' => [
    'header' => "Authorization: Bearer tk_your_key\r\n",
]]);
$res = file_get_contents('https://tinyzy.com/api/v1/links', false, $ctx);
$data = json_decode($res, true);

const res  = await fetch('https://tinyzy.com/api/v1/links', {
  headers: { 'Authorization': 'Bearer tk_your_key' }
});
const data = await res.json();
console.log(data.data);   // array of links
console.log(data.meta);   // pagination info

import requests

r = requests.get(
    'https://tinyzy.com/api/v1/links',
    headers={'Authorization': 'Bearer tk_your_key'},
    params={'page': 1, 'per_page': 20}
)
data = r.json()

Response

{
  "data": [
    {
      "id":          1,
      "slug":        "abc123",
      "title":       "My Campaign",
      "destination": "https://example.com/page",
      "clicks":      142,
      "status":      "active",
      "created_at":  "2025-03-01 09:22:11"
    }
  ],
  "meta": {
    "page":        1,
    "per_page":    20,
    "total":       48,
    "total_pages": 3
  }
}

POST /api/v1/links Create a short link

Creates a new short link. Accepts application/json or application/x-www-form-urlencoded.

Body Parameters

Name	Type	Required	Description
destination	string	Required	The long URL to shorten
slug	string	Optional	Custom slug — auto-generated if omitted
title	string	Optional	Human-readable label

curl -X POST "https://tinyzy.com/api/v1/links" \
     -H "Authorization: Bearer tk_your_key" \
     -H "Content-Type: application/json" \
     -d '{"destination":"https://example.com","slug":"my-link","title":"My Link"}'

<?php
$payload = json_encode([
    'destination' => 'https://example.com/page',
    'slug'        => 'my-link',
    'title'       => 'My Link',
]);
$ctx = stream_context_create(['http' => [
    'method'  => 'POST',
    'header'  => "Authorization: Bearer tk_your_key\r\nContent-Type: application/json\r\n",
    'content' => $payload,
]]);
$res  = file_get_contents('https://tinyzy.com/api/v1/links', false, $ctx);
$data = json_decode($res, true);
echo $data['short_url'];

const res = await fetch('https://tinyzy.com/api/v1/links', {
  method:  'POST',
  headers: {
    'Authorization': 'Bearer tk_your_key',
    'Content-Type':  'application/json',
  },
  body: JSON.stringify({
    destination: 'https://example.com/page',
    slug:        'my-link',
    title:       'My Link',
  }),
});
const data = await res.json();
console.log(data.short_url);

import requests

r = requests.post(
    'https://tinyzy.com/api/v1/links',
    headers={'Authorization': 'Bearer tk_your_key'},
    json={
        'destination': 'https://example.com/page',
        'slug':        'my-link',
        'title':       'My Link',
    }
)
print(r.json()['short_url'])

Response 201 Created

{
  "data": {
    "id":          49,
    "slug":        "my-link",
    "title":       "My Link",
    "destination": "https://example.com/page",
    "clicks":      0,
    "status":      "active",
    "created_at":  "2025-03-16 14:00:00"
  },
  "short_url": "https://tinyzy.com/my-link"
}

GET /api/v1/links/{id} Get a single link

Retrieves a single link by its numeric ID. Returns 404 if not found or if the link belongs to another user.

Path Parameters

Name	Type	Required	Description
id	integer	Required	Link ID

curl -X GET "https://tinyzy.com/api/v1/links/49" \
     -H "Authorization: Bearer tk_your_key"

const res  = await fetch('https://tinyzy.com/api/v1/links/49', {
  headers: { 'Authorization': 'Bearer tk_your_key' }
});
const data = await res.json();
console.log(data.data.slug, data.short_url);

r = requests.get(
    'https://tinyzy.com/api/v1/links/49',
    headers={'Authorization': 'Bearer tk_your_key'}
)
print(r.json()['short_url'])

Response

{
  "data":      { /* link object */ },
  "short_url": "https://tinyzy.com/abc123"
}

DELETE /api/v1/links/{id} Permanently delete a link

Permanently deletes a short link and all its analytics data. This action cannot be undone.

curl -X DELETE "https://tinyzy.com/api/v1/links/49" \
     -H "Authorization: Bearer tk_your_key"

await fetch('https://tinyzy.com/api/v1/links/49', {
  method:  'DELETE',
  headers: { 'Authorization': 'Bearer tk_your_key' },
});

requests.delete(
    'https://tinyzy.com/api/v1/links/49',
    headers={'Authorization': 'Bearer tk_your_key'}
)

Response 200

{ "message": "Link deleted" }

PATCH /api/v1/links/{id}/pause Pause a link

Pauses a short link. Visitors who follow the short URL will see an inactive page instead of being redirected.

curl -X PATCH "https://tinyzy.com/api/v1/links/49/pause" \
     -H "Authorization: Bearer tk_your_key"

await fetch('https://tinyzy.com/api/v1/links/49/pause', {
  method:  'PATCH',
  headers: { 'Authorization': 'Bearer tk_your_key' },
});

Response

{ "message": "Link paused" }

PATCH /api/v1/links/{id}/activate Re-activate a paused link

Re-activates a previously paused short link so it resumes redirecting visitors.

curl -X PATCH "https://tinyzy.com/api/v1/links/49/activate" \
     -H "Authorization: Bearer tk_your_key"

await fetch('https://tinyzy.com/api/v1/links/49/activate', {
  method:  'PATCH',
  headers: { 'Authorization': 'Bearer tk_your_key' },
});

Response

{ "message": "Link activated" }

POST /api-keys/create Generate a new API key

Generates a new API key for the authenticated user. The token is only shown once — store it securely immediately after creation.

Body Parameters

Name	Type	Required	Description
label	string	Optional	Friendly name, default `"My API Key"`

Response

{
  "status": "success",
  "token":  "tk_a3f8c9d2e14b...48 hex chars...",
  "label":  "My Production Key"
}

GET /api-keys/list List your API keys

Returns all API keys for the authenticated user. Token values are masked — only the first 12 characters are returned.

Response

{
  "status": "success",
  "keys": [
    {
      "id":            1,
      "label":         "My Production Key",
      "token_preview": "tk_a3f8c9d2...",
      "last_used_at":  "2025-03-15 18:30:00",
      "created_at":    "2025-03-01 09:00:00"
    }
  ]
}

POST /api-keys/delete/{id} Revoke an API key

Permanently revokes an API key by ID. Any requests using this key will immediately start returning 401 Unauthorized.

Response

{ "status": "success", "message": "Key deleted" }

Developer API