Integrate with the
Yrkus API
Build powerful link management and QR code solutions directly into your applications. Authenticate, create, manage links, and generate QR codes programmatically.
How to Get Started
- Request Your Key: Click the button above to email us.
- Check Docs: Review the authentication and endpoints below.
- Secure It: Treat your API key like a password.
API Features
1 Authentication
Yrkus uses API keys to allow access to the API.
Method A: Header (Recommended)
Use this for all data endpoints (Creating links, getting stats).
Authorization: Bearer YOUR_API_KEY
Method B: URL Parameter
Use this only for the Image Endpoint (GET /api/qr), as HTML <img> tags cannot send headers.
https://www.yrk.us/api/qr/abc1?api_key=YOUR_API_KEY
2 Quick Start Code
Choose your language to create a short link in seconds.
$ch = curl_init('https://www.yrk.us/api/links');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer YOUR_KEY',
'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
'long_url' => 'https://google.com'
]));
$response = curl_exec($ch);
curl_close($ch);
import requests
url = "https://www.yrk.us/api/links"
headers = {
"Authorization": "Bearer YOUR_KEY",
"Content-Type": "application/json"
}
data = {"long_url": "https://google.com"}
response = requests.post(url, json=data, headers=headers)
print(response.json())
fetch('https://www.yrk.us/api/links', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({ long_url: 'https://google.com' })
})
.then(res => res.json())
.then(data => console.log(data));
package main
import (
"bytes"
"net/http"
)
func main() {
url := "https://www.yrk.us/api/links"
jsonStr := []byte(`{"long_url":"https://google.com"}`)
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonStr))
req.Header.Set("Authorization", "Bearer YOUR_KEY")
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
String json = "{\"long_url\":\"https://google.com\"}";
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://www.yrk.us/api/links"))
.header("Authorization", "Bearer YOUR_KEY")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(json))
.build();
client.send(request, HttpResponse.BodyHandlers.ofString());
using System.Net.Http;
using System.Text;
using System.Text.Json;
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_KEY");
var json = JsonSerializer.Serialize(new { long_url = "https://google.com" });
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://www.yrk.us/api/links", content);
require 'uri'
require 'net/http'
require 'json'
uri = URI('https://www.yrk.us/api/links')
req = Net::HTTP::Post.new(uri, {
'Authorization' => 'Bearer YOUR_KEY',
'Content-Type' => 'application/json'
})
req.body = {long_url: 'https://google.com'}.to_json
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(req)
end
3 Link Management
Create a new short URL. You can optionally set an expiration date, password, or custom alias.
Parameters (JSON Body)
long_url (string) |
Required The destination URL (e.g., https://google.com). |
custom_slug (string) |
Optional A custom alias (e.g., 'summer-sale'). |
user_phone (string) |
Optional Link this URL to a specific user phone number for history tracking. |
password (string) |
Optional Password protect the link. |
expires_at (string) |
Optional Date string (e.g., "2025-12-31 23:59:00"). |
Retrieve a list of all active links created by your API Key.
Get details/stats for a single specific link.
Soft-delete a link (move to recycle bin).
Note: If the link was created with a user_phone, you must provide that phone number in the body to authorize the deletion.
user_phone (string) |
Optional JSON Body. Required only if link belongs to a phone user. |
4 QR Codes
Dynamic vs. Static QR Codes
Both QR endpoints below accept an optional qr_type parameter that controls what gets encoded into the QR image, and whether a short link is created for it:
- dynamic (default) — Shortens the destination first, then encodes the short URL (
https://yrk.us/xxxx) into the QR. Because the QR points at a redirect, you can update the destination later without reprinting the code, and clicks are tracked. This creates a link in your account, visible via GET /api/links. - static — Encodes your
long_urldirectly into the QR. No shortening happens and nothing is saved to your account — use this when you don't need click tracking, or want the QR to keep working even if your Yrkus account or the short link is ever removed.
Use case: You want to generate a short link AND get the QR code data (Base64) in one request to save in your database.
long_url (string) |
Required The URL to shorten and encode (or the URL to encode directly if qr_type is static). |
qr_type (string) |
Optional dynamic (default) or static. See Dynamic vs. Static above. |
size (integer) |
Optional Default: 300px. |
color (string) |
Optional Hex color without # (e.g., '000000'). |
bg_color (string) |
Optional Background hex color without # (default: ffffff). |
margin (integer) |
Optional Padding in pixels (default: 10). |
Example Response — Dynamic (default)
{
"status": "success",
"qr_type": "dynamic",
"short_url": "https://yrk.us/aB3x",
"stats_url": "https://yrkus.com/statistics.php?code=aB3x",
"qr_code": "data:image/png;base64,iVBORw0KGgo..."
}
Example Response — Static
{
"status": "success",
"qr_type": "static",
"target_url": "https://example.com/some/long/page",
"qr_code": "data:image/png;base64,iVBORw0KGgo..."
}
Note: a static response has no short_url or stats_url — nothing was shortened or saved.
Use case: You want to display a QR code directly in an app or website using an <img> tag.
api_key (string) |
Required Your API Key (passed in URL). |
url (string) |
Required The URL to shorten. (Required if you are not using /api/qr/{code}). |
size (integer) |
Optional Size in pixels (default: 300). |
color (string) |
Optional Foreground hex color (e.g., ff0000). |
qr_type (string) |
Optional dynamic (default) or static. Only applies when using ?url= — ignored on /api/qr/{short_code}, since an existing short code is always dynamic. |
Alternative: Auto-Shorten
If you don't have a short code yet, pass the long URL directly. The API will shorten it and return the image.
⚠️ Security Architecture Requirements
Do not inject your master API key directly into client-side code blocks or markdown HTML components.
Even if initialized within server environment environments or isolated storage variables (e.g. $apikey), rendering parameters explicitly on user-facing <img> target attributes reveals your private key to raw traffic scanners and browser inspector utilities.
Recommended Implementation Pattern (Server-to-Server Proxy):
- Point your raw page markup structure to a localized route on your own domain (e.g.,
<img src="/render-qr.php?url=https://example.com" />). - In your backend server environment file (
render-qr.php), hold yourYRK_API_KEYvariable safely out of client reach. - Perform a backend
file_get_contents()request to our API endpoint from your server context, then stream the raw data payload out safely using animage/pngresponse header block.
Secure Integration (Recommended Method)
To prevent exposing your API key on the frontend, always use a backend proxy endpoint. This ensures your key stays hidden while the server handles API requests securely.
Frontend Usage (Safe Method)
This method hides your API key completely because the browser only talks to your server, not directly to the API.
Example Implementations (Other Languages)
You can call the API from any backend language. Below are common examples:
Mobile App Integration
You can use this API in Android and iOS apps by simply loading the image URL.
5 Errors & Rate Limits
Rate Limiting
This API uses a Fixed Window strategy. You have a set limit of requests per 60 seconds. If you exceed this, you will receive a 429 Too Many Requests error.
Malicious URLs
All URLs are scanned against the Google Safe Browsing API. If a URL is flagged as unsafe, the API will return a 400 Bad Request and refuse to shorten it.
| Code | Meaning |
|---|---|
400 | Missing parameters or Malicious URL detected. |
401 | Invalid API Key. |
403 | API Key Suspended. |
404 | Resource not found. |
429 | Rate limit exceeded (Wait ~60 seconds). |
Stay in the loop
Join our newsletter to get the latest updates on Yrkus features, API changes, and maintenance schedules.
We care about your data. Read our Privacy Policy.