API Documentation

Integrate SMO1.io link shortening and analytics into your applications using our REST API.

Getting Started

The SMO1.io API allows you to programmatically create shortened links, retrieve analytics, and manage your account. All API endpoints are available at:

https://api.smo1.io/v1

Authentication

All API requests must include an API key in the Authorization header. You can generate API keys from your account settings.

Authorization: Bearer your_api_key_here

The number of API keys you can create depends on your plan tier. Free accounts get 1 API key, Pro accounts get up to 5.

Rate Limits

API requests are rate-limited based on your plan tier. Rate limit information is included in response headers:

Plan	Rate Limit	Max Links
Free	60 req/min	25
Pro	300 req/min	Unlimited
Business	1000 req/min	Unlimited

When you exceed the rate limit, the API returns a 429 Too Many Requests response. Check the Retry-After header for when you can retry.

Create a Short Link

POST/v1/links

Create a new shortened link. You can optionally provide a custom slug.

Request Body

{
  "url": "https://example.com/very-long-url",
  "slug": "my-custom-slug",    // optional
  "title": "My Link"           // optional
}

Response

{
  "id": "link_abc123",
  "short_url": "https://smo1.io/my-custom-slug",
  "original_url": "https://example.com/very-long-url",
  "slug": "my-custom-slug",
  "title": "My Link",
  "clicks": 0,
  "created_at": "2026-02-15T12:00:00Z"
}

List Links

GET/v1/links

Retrieve a paginated list of your links.

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 20, max: 100)
`search`	string	Filter links by title or URL

Response

{
  "links": [
    {
      "id": "link_abc123",
      "short_url": "https://smo1.io/my-slug",
      "original_url": "https://example.com",
      "slug": "my-slug",
      "clicks": 42,
      "created_at": "2026-02-15T12:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

Get Link Analytics

GET/v1/links/:slug/analytics

Retrieve detailed analytics for a specific link, including click counts by time period, geographic breakdown, device types, and referrers.

Query Parameters

Parameter	Type	Description
`period`	string	Time period: `24h`, `7d`, `30d`, `90d`

Response

{
  "total_clicks": 1234,
  "clicks_by_date": [
    { "date": "2026-02-14", "clicks": 56 },
    { "date": "2026-02-15", "clicks": 78 }
  ],
  "countries": [
    { "country": "US", "clicks": 500 },
    { "country": "GB", "clicks": 200 }
  ],
  "devices": [
    { "device": "desktop", "clicks": 700 },
    { "device": "mobile", "clicks": 534 }
  ],
  "referrers": [
    { "referrer": "twitter.com", "clicks": 300 },
    { "referrer": "direct", "clicks": 450 }
  ]
}

Delete a Link

DELETE/v1/links/:slug

Permanently delete a shortened link. This action cannot be undone. The short URL will stop redirecting immediately and associated analytics data will be removed.

Response

{
  "message": "Link deleted successfully"
}

Error Handling

The API uses standard HTTP status codes. Error responses include a JSON body with details:

{
  "error": {
    "code": "validation_error",
    "message": "Invalid URL format"
  }
}

Status Code	Description
`400`	Bad Request — Invalid parameters
`401`	Unauthorized — Missing or invalid API key
`404`	Not Found — Resource does not exist
`409`	Conflict — Slug already taken
`429`	Too Many Requests — Rate limit exceeded
`500`	Internal Server Error — Something went wrong

SDKs and Libraries

Official SDKs are coming soon. In the meantime, you can use the REST API directly with any HTTP client. The API accepts and returns JSON, so it works seamlessly with tools like curl, fetch, or any HTTP library in your preferred language.

Need Help?

If you have questions about the API or need assistance, contact us at support@smo1.io. We are happy to help you get started.