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.
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:
| 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 onrby.oneor 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, andRetry-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, and500 Internal Server Error. - Interactive API Reference: Explore and test available endpoints directly in your browser using the Interactive API Reference (Swagger UI).
4. Quickstart: Create Your First Short Link¶
Follow this minimal example to generate a short link in less than 2 minutes:
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¶
- Postman Collection & Quickstart — Fork our public Postman workspace or download pre-configured collections and environments.
- API Authentication Guide — Learn how to generate API keys, configure Bearer tokens, and sign requests with HMAC-SHA256.
- Rate Limits & Error Handling — Understand token bucket capacity and rate limit headers.
- Interactive API Reference (Swagger UI) — Test all endpoints interactively in your browser.
- OpenAPI 3.1 Specification — Download the machine-readable OpenAPI schema to generate client SDKs.