Developers

The Forkly REST API

Create smart links from your backend, CMS or CI pipeline, pull analytics into your warehouse and render QR codes on demand. JSON in, JSON out.

Create an account Jump to examples

Overview

The API is organised around REST resources, uses standard HTTP verbs and status codes, and always returns JSON (except image endpoints). All requests must use HTTPS.

Base URL: https://1link.1workspace.in/api/v1
Format: JSON request bodies with Content-Type: application/json
Pagination: page and pageSize query parameters; list responses include total and totalPages
Timestamps: ISO 8601 strings in UTC

Authentication

Authenticate every request with an API key sent as a bearer token. Keys start with fk_live_ and belong to a single workspace, so you never need to pass a workspace ID.

Open Dashboard → API keys. API access is included on the Business plan.
Name the key, choose its scopes and, optionally, an expiry.
Copy the secret immediately — it is shown only once. You can regenerate or revoke a key at any time.

bashAuthenticated request

curl https://1link.1workspace.in/api/v1/links \
  -H "Authorization: Bearer fk_live_your_api_key"

Treat keys like passwords: keep them server-side, never embed them in mobile apps or browser code, and rotate them if they may have leaked.

Scopes

Each key is limited to the scopes you grant. Requests outside a key’s scopes fail with 403.

links:read
List links and read a single link.
links:write
Create, update and delete links.
analytics:read
Read summaries, timeseries and breakdowns.
qr:read
Render QR code images for links.
domains:read
List the domains available to the workspace.

Links

A link has a defaultUrl, an optional fallbackUrl, per-platform destinations (IOS, IPAD, ANDROID, HUAWEI, AMAZON, WINDOWS, MACOS, LINUX), ordered rules and utm parameters.

GET/api/v1/linkslinks:read

List links

Query parameters for listing links
Parameter	Type	Description
q	string	Search by name, slug or destination.
status	string	all · active · inactive · archived · expired · suspended
tag	string	Only links with this tag.
domainId	string	Only links on this domain.
sort	string	-createdAt · createdAt · -clicks · clicks · name · -name · -lastClickedAt
page, pageSize	integer	Pagination controls.

json200 OK

{
  "items": [
    {
      "id": "clx0k3v9w0001",
      "name": "Summer launch",
      "slug": "summer",
      "shortUrl": "https://go.example.com/summer",
      "defaultUrl": "https://example.com/app",
      "destinations": [{ "platform": "IOS", "url": "https://apps.apple.com/app/id1234567890", "deepLinkUrl": null }],
      "status": "active",
      "totalClicks": 0,
      "totalQrScans": 0,
      "createdAt": "2026-09-24T09:00:00.000Z"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 1,
  "totalPages": 1
}

POST/api/v1/linkslinks:write

Create a link

Body fields for creating a link
Parameter	Type	Description
namerequired	string	Internal name, up to 120 characters.
defaultUrlrequired	url	Where visitors go when nothing more specific matches.
slug	string	Custom back-half. Generated when omitted.
domainId	string	Domain to create the link on. Defaults to the workspace default domain.
fallbackUrl	url \| null	Used for platforms without a destination.
destinations	array	Objects of `{ platform, url, deepLinkUrl? }`, one per platform.
rules	array	Up to 25 objects of `{ name, countries?, operatingSystems?, deviceTypes?, languages?, destinationUrl }`. Pro and Business.
utm	object	`{ source, medium, campaign, term, content }` appended to destinations.
password	string \| null	Protect the link with a password. Pro and Business.
expiresAt, clickLimit	ISO date, integer	Stop routing after a date or a number of clicks. Pro and Business.
tags, notes, isActive, forwardQueryParams	mixed	Organisation and behaviour flags.

Returns 201 with the created link, including its shortUrl. See the full request in Examples.

GET/api/v1/links/:idlinks:read

Retrieve a link

PATCH/api/v1/links/:idlinks:write

Update a link

Send only the fields you want to change. Pass "password": null to remove a password. Changes apply to the next visitor.

DELETE/api/v1/links/:idlinks:write

Delete a link

Deleted slugs are quarantined for 30 days before they can be reused, so old QR codes cannot be hijacked.

Analytics

All analytics endpoints share the same filters.

Shared analytics query parameters
Parameter	Type	Description
range	string	One of `today`, `yesterday`, `7d`, `30d` (default), `90d`, `custom`.
from, to	YYYY-MM-DD	Required when `range=custom`. Ranges are clipped to your plan’s analytics history.
linkId	string	Limit results to a single link.
source	string	`all` (default), `link` for clicks only or `qr` for QR scans only.

GET/api/v1/analyticsanalytics:read

Summary

Totals for clicks, uniqueVisitors and qrScans, each with a change versus the previous period, plus the resolved range.

GET/api/v1/analytics/timeseriesanalytics:read

Timeseries

Points of { t, clicks, qrScans, uniqueVisitors } by hour or day depending on the range.

GET/api/v1/analytics/breakdownanalytics:read

Breakdown

Breakdown query parameters
Parameter	Type	Description
dimensionrequired	string	country · city · device · os · browser · referrer · platform · utm_source · utm_medium · utm_campaign
limit	integer	Rows to return, 1–250 (default 10).

Returns rows of { value, label, clicks, share }. City and UTM dimensions require Pro or Business.

QR codes

GET/api/v1/links/:id/qr/imageqr:read

Render a QR image

QR image query parameters
Parameter	Type	Description
format	string	`png` or `svg`.
size	integer	Width in pixels, 128–4096.
download	1	Adds a Content-Disposition header for file downloads.

The image uses the link’s saved QR design (colours, shapes and logo).

bashDownload a 1024px PNG

curl -o summer.png \
  "https://1link.1workspace.in/api/v1/links/LINK_ID/qr/image?format=png&size=1024" \
  -H "Authorization: Bearer fk_live_your_api_key"

Domains

GET/api/v1/domainsdomains:read

List domains

Returns the shared platform domain and your custom domains with status (PENDING, VERIFIED, FAILED), isDefault, linkCount and the DNS records to configure. Use a domain’s id as domainId when creating links.

Errors

Errors use conventional HTTP status codes and a consistent body. fieldErrors maps field paths to messages for validation failures. Include the requestId when contacting support.

httpError response

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "statusCode": 400,
  "code": "VALIDATION_FAILED",
  "message": "Some fields are invalid",
  "fieldErrors": {
    "destinations.0.url": ["Enter a valid https:// URL"]
  },
  "requestId": "req_7f3c2a9e41b0"
}

HTTP status codes
400	The request is malformed or failed validation (code VALIDATION_FAILED).
401	Missing, invalid, expired or revoked API key.
402	The feature or limit requires a higher plan (FEATURE_NOT_IN_PLAN or PLAN_LIMIT_REACHED).
403	The key lacks the required scope.
404	The resource does not exist in this workspace.
409	Conflict, such as a slug that is already taken.
429	Rate limit exceeded (RATE_LIMITED) — wait Retry-After seconds.
5xx	Something went wrong on our side. Retry with backoff.

Rate limits

Each API key can make 600 requests per minute. Every response includes RateLimit-Limit and RateLimit-Remaining headers. When you exceed the limit you receive 429 with a Retry-After header in seconds.

httpRate limit headers

HTTP/1.1 200 OK
RateLimit-Limit: 600
RateLimit-Remaining: 587

HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 600
RateLimit-Remaining: 0
Retry-After: 23

Examples

Create a link that sends iPhone and Android users to their stores, routes visitors in Germany to a localised page, and tags every visit with UTM parameters.

bashcURL

curl -X POST https://1link.1workspace.in/api/v1/links \
  -H "Authorization: Bearer fk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Summer launch",
  "defaultUrl": "https://example.com/app",
  "destinations": [
    {
      "platform": "IOS",
      "url": "https://apps.apple.com/app/id1234567890"
    },
    {
      "platform": "ANDROID",
      "url": "https://play.google.com/store/apps/details?id=com.example.app"
    }
  ],
  "rules": [
    {
      "name": "Germany",
      "countries": [
        "DE"
      ],
      "destinationUrl": "https://example.com/de/app"
    }
  ],
  "utm": {
    "source": "newsletter",
    "medium": "email",
    "campaign": "summer-launch"
  }
}'

jsJavaScript (Node 18+ / fetch)

const res = await fetch('https://1link.1workspace.in/api/v1/links', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.FORKLY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Summer launch",
    "defaultUrl": "https://example.com/app",
    "destinations": [
      {
        "platform": "IOS",
        "url": "https://apps.apple.com/app/id1234567890"
      },
      {
        "platform": "ANDROID",
        "url": "https://play.google.com/store/apps/details?id=com.example.app"
      }
    ],
    "rules": [
      {
        "name": "Germany",
        "countries": [
          "DE"
        ],
        "destinationUrl": "https://example.com/de/app"
      }
    ],
    "utm": {
      "source": "newsletter",
      "medium": "email",
      "campaign": "summer-launch"
    }
  }),
});

if (!res.ok) {
  const error = await res.json(); // { statusCode, code, message, fieldErrors, requestId }
  throw new Error(`${error.code}: ${error.message}`);
}

const link = await res.json();
console.log(link.shortUrl);

Questions or feedback about the API? Contact our team.