Postman Collection & Quickstart Guide¶
The fastest way to explore, test, and integrate the Ruby Developer REST API is through our official Postman collection and public workspace.
1. Quickstart: Open in Postman¶
The fastest and recommended way to get started is to fork our official collection directly in the Postman Public Workspace. When you fork from our public workspace, Postman automatically notifies you of new endpoints, schema changes, and parameter updates as our API evolves.
Prefer manual file import or offline use? (Click to view downloads)
If you are developing in an offline environment or prefer importing raw files manually into Postman or Insomnia:
| Resource | Description | Format | Download |
|---|---|---|---|
| API Collection | Complete request collection with automatic HMAC pre-request scripts | JSON | RubyOne_API.postman_collection.json |
| Environment | Pre-configured production environment preset | JSON | RubyOne_Environment.postman_environment.json |
| OpenAPI 3.1 Spec | Authoritative OpenAPI 3.1 specification schema | JSON | openapi_v1.json |
2. Configuring Environment Variables¶
Once you have imported or forked the collection, activate the Ruby API (Production) environment and configure the following variables:
| Variable | Required | Description | Example / Default |
|---|---|---|---|
baseUrl |
Yes | Root API URL | https://api.rby.one |
authMethod |
Yes | Authentication type (bearer or hmac) |
bearer |
apiKeyId |
Yes | Your API Key ID from CMS | ak_01J8K92M4 |
apiKeySecret |
If Bearer | API Key Secret (used when authMethod is bearer) |
as_9f8a7b6c5d4e3f2... |
hmacSecret |
If HMAC | HMAC Secret (used when authMethod is hmac) |
hs_9f8a7b6c5d4e3f2... |
defaultDomain |
Optional | Default short domain | rby.one |
shortCode |
Optional | Sample short code for lookup requests | sample123 |
linkPublicId |
Optional | Sample link public ID for single link endpoints | lnk_sample123 |
groupPublicId |
Optional | Sample group public ID for group endpoints | grp_sample123 |
Where to Find Your Credentials
You can generate and manage API keys under Settings > Developer > API Keys in the Ruby CMS. For detailed guidance, see API Authentication.
3. Built-In Pre-Request Script Automation¶
The collection includes a pre-request script at the collection root that handles authentication dynamically for every request:
- When
authMethodis set tobearer: It automatically constructs theAuthorization: Bearer <apiKeyId>:<apiKeySecret>header. - When
authMethodis set tohmac: It automatically generates the required enterprise cryptographic signature headers: X-Rby-Key-Id: Your API Key ID (apiKeyId).X-Rby-Timestamp: Current UTC Unix timestamp.X-Rby-Signature: Computed signature usingCryptoJS.HmacSHA256(canonicalString, hmacSecret).
This enables you to switch between standard Bearer tokens and enterprise cryptographic HMAC signing by toggling a single variable in your Postman environment.
4. Pre-Configured Endpoints Included¶
The collection is organized by resource and contains ready-to-execute requests for all 18 public API operations:
Links (/v1/links)¶
- Create Short Link: Create short links on
rby.oneor verified custom domains with optional device targeting (ios_url,android_url), password gates, expiration timestamps, and OpenGraph tags. - List Short Links: Query links with pagination (
cursor,limit) and status filters. - Get Short Link: Fetch link details and metadata by public ID.
- Update Short Link: Modify destination URLs, titles, expiration dates, or targeting rules.
- Archive Short Link: Safely archive links without breaking redirect history.
Groups (/v1/groups)¶
- Create Link Group: Create campaign collections for categorized link tracking.
- List Link Groups: Paginate through active campaign groups.
- Get Link Group: Fetch group summary metrics and link counters.
- Update Link Group: Update group title or description.
- Batch Create Links in Group: Programmatically create batches of up to 500 links within a group.
- Delete Link Group: Soft-delete or hard-delete (
?hard=true) campaign groups. - List Group Links: Retrieve links belonging to a specific group.
- Export Group Links: Request or download CSV link datasets (
?refresh=true).
Domains (/v1/domains)¶
- List Branded Domains: View all custom domains associated with your organization.
- Get Branded Domain: Inspect domain verification status and routing configurations.
- Verify Domain DNS: Trigger instant DNS validation checks (
CNAME/A/TXT).
Analytics (/v1/analytics)¶
- Link Clickstream Timeseries: Query time-series click counts, unique visitors, and device/geographic distributions.
System (/v1/health)¶
- Health Check: Verify API service operational status.
5. Standalone Code Examples¶
If you are developing outside Postman, the companion GitHub repository includes tested scripts for both Bearer and HMAC authentication across three languages:
- cURL:
examples/curl/create_link_bearer.sh— Standard link creation via Bearer authexamples/curl/create_link_hmac.sh— Link creation via HMAC-SHA256 request signingexamples/curl/create_group.sh— Campaign group creationexamples/curl/list_domains.sh— Branded domain listing- Python:
examples/python/create_link_bearer.py— Link creation usingrequestswith Bearer authexamples/python/create_link_hmac.py— Canonical HMAC-SHA256 request signingexamples/python/create_group.py— Group creationexamples/python/list_domains.py— Domain listing- Node.js:
examples/node/create_link_bearer.js— Nativefetchwith Bearer authexamples/node/create_link_hmac.js— Node.jsnode:cryptoHMAC-SHA256 request signingexamples/node/create_group.js— Group creationexamples/node/list_domains.js— Domain listing
6. Resources & Next Steps¶
- API Overview — Base URLs, technical specifications, and quickstart examples.
- API Authentication — In-depth guide to Bearer vs. HMAC-SHA256 signing.
- Rate Limits & Error Handling — Understand token bucket capacity and HTTP error formats.
- Interactive API Reference (Swagger UI) — Test all endpoints interactively in your browser.