Suff is a URL shortening service that converts long URLs into compact, shareable links.

The Suff API allows you to programmatically:

• Create short links
• Retrieve a paginated list of your short links
• Delete short links

Base URL

https://suff.me/api/v1/

Request & Response Format

All requests and responses use Content-Type: application/json.

API Versioning

The current version is v1, indicated in the URL path (/api/v1/). Future versions will be released under /api/v2/ etc.

The API uses Bearer token authentication via the HTTP Authorization header. Your token is called the Secret and is tied to your Suff user account.

How to get a Secret

1. Log in to your Suff account.
2. Go to API Secret in the sidebar (or navigate to /credential).
3. Click Generate Secret.
4. Copy the displayed token ÔÇö treat it like a password; do not share it.
5. To revoke access, click Delete Secret. To rotate the token, click Regenerate Secret.

Using the Secret

Include the token in every API request via the Authorization header:

Authorization: Bearer <your-secret>

Example

curl -H "Authorization: Bearer H5iVunjypxoyL8bcbRfBNrRyYj8QfPxW" \n     https://suff.me/api/v1/short-links

Error when token is missing or invalid

{ "status": 401, "message": "Your request was made with invalid credentials." }

Shorten a URL by posting it to the API. If the same URL was already shortened by the same user, the existing record is returned ÔÇö no duplicate is created.

Request Headers

Authorization: Bearer <your-secret>
Content-Type: application/json

Request Body

{
  "url": "https://example.com/very/long/path?with=query"
}

Success ÔÇö 201 Created

{
  "id": 42,
  "url": "https://example.com/very/long/path?with=query",
  "uri": "dOYacYg",
  "short_url": "https://suff.me/dOYacYg",
  "created_at": 1709380000
}

short_url is the ready-to-use shortened link.

Validation Error ÔÇö 400 Bad Request

{
  "status": 400,
  "message": "Validation failed.",
  "errors": {
    "url": ["URL is not valid."]
  }
}

Retrieve a paginated list of short links belonging to the authenticated user. Results are ordered newest first.

Query Parameters

Success ÔÇö 200 OK

{
  "items": [
    {
      "id": 42,
      "url": "https://example.com/very/long/path?with=query",
      "uri": "dOYacYg",
      "short_url": "https://suff.me/dOYacYg",
      "created_at": 1709380000
    }
  ],
  "pagination": {
    "total": 85,
    "page": 1,
    "per_page": 20,
    "total_pages": 5
  }
}

created_at is a Unix timestamp (seconds since epoch).

Permanently delete a short link by its ID. Only the owner of the link may delete it.

Path Parameter

Success ÔÇö 204 No Content

Empty response body on success.

Error Responses