Skip to content

Developer REST API

The Ruby REST API enables programmatic access to short link management, custom branded domains, link campaigns, vector QR codes, and real-time clickstream analytics.

OpenAPI 3.1 GitHub Repository Run in Postman

Use the API to automate link creation, enforce password gates and expiration dates, configure device-specific app store routing (iOS/Android), generate vector QR codes, batch-import URLs into campaign groups, and export CSV reports. You can also explore and fork our Official Postman Collection.


1. Base URL

All API endpoints are served securely over HTTPS (TLS 1.3) and use the /v1 version prefix:

https://api.rby.one/v1
Environment Base URL Health Check
Production https://api.rby.one/v1 https://api.rby.one/v1/health

2. API Capabilities

  • Short Links (/v1/links)
    Create, retrieve, update, and archive shortened links on rby.one or verified custom branded domains. Configure device targeting (ios_url, android_url), OpenGraph social preview tags, password gates, and expiration dates.
  • Dynamic QR Codes (/v1/links/{public_id}/qr)
    Fetch vector SVG or PNG QR codes for any short link on demand with customizable colors, error correction, and embedded logos.
  • Link Groups (/v1/groups)
    Organize short links into campaign collections, retrieve aggregated metrics, programmatically batch create links, and asynchronously export CSV datasets.
  • Branded Domains (/v1/domains)
    Inspect custom branded domains, verify DNS records (CNAME / A / TXT), and manage custom domain routing.
  • Clickstream Analytics (/v1/analytics)
    Retrieve time-series click metrics, unique visitors, bot filtering, and categorical breakdowns (devices, browsers, operating systems, referrers, and countries).

3. Key Technical Specifications

  • JSON API: Request and response bodies use UTF-8 encoded JSON.
  • Dual Authentication: Authenticate API requests using Bearer credentials (Authorization: Bearer <key_id>:<key_secret>) or enterprise cryptographic HMAC-SHA256 request signing (X-Rby-Key-Id, X-Rby-Timestamp, X-Rby-Signature). See API Authentication.
  • Rate Limiting: API requests are governed by a token-bucket rate limiter per organization tier with standard response headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After). See Rate Limits & Errors.
  • Standard HTTP Errors: Standard HTTP status codes are returned, including 200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable Entity, 429 Too Many Requests, and 500 Internal Server Error.
  • Interactive API Reference: Explore and test available endpoints directly in your browser using the Interactive API Reference (Swagger UI).

Follow this minimal example to generate a short link in less than 2 minutes:

curl -X POST "https://api.rby.one/v1/links" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ak_01J8K92M4:as_9f8a7b6c5d4e3f2a1b0c" \
  -d '{
    "destination_url": "https://example.com/promotion",
    "domain": "rby.one",
    "title": "Summer Campaign Launch"
  }'
import requests

API_URL = "https://api.rby.one/v1/links"
AUTH_TOKEN = "ak_01J8K92M4:as_9f8a7b6c5d4e3f2a1b0c"

payload = {
    "destination_url": "https://example.com/promotion",
    "domain": "rby.one",
    "title": "Summer Campaign Launch"
}

response = requests.post(
    API_URL,
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {AUTH_TOKEN}"
    },
    json=payload
)
print(response.status_code, response.json())
const AUTH_TOKEN = "ak_01J8K92M4:as_9f8a7b6c5d4e3f2a1b0c";

const response = await fetch("https://api.rby.one/v1/links", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${AUTH_TOKEN}`
  },
  body: JSON.stringify({
    destination_url: "https://example.com/promotion",
    domain: "rby.one",
    title: "Summer Campaign Launch"
  })
});

const data = await response.json();
console.log(response.status, data);

5. Next Steps