Link management API

Seven endpoints for managing your organization's deep links from any HTTP client — no SDK required. Every request authenticates with your Server API Key:

Authorization: Bearer opl_api_…

A mobile SDK key (opl_sdk_…) on these routes returns 403. Plan and org rules match the portal: links count against your plan's quota, and your org must have a registered app config before the first link. See Plans & pricing for the limits.

Endpoints

Method	Path	Purpose
POST	/links	Create a deep link
GET	/links	List links (paginated)
GET	/links/:id	Read one link
PATCH	/links/:id	Update a link
DELETE	/links/:id	Delete a link
GET	/links/:id/qr.svg	QR code as SVG
GET	/links/:id/qr.png	QR code as PNG

Create a link

curl -X POST https://<your-optolink-host>/links \
  -H "Authorization: Bearer opl_api_…" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/product/123",
    "domainId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'

path (the in-app destination, e.g. /product/123) is the one required field. Omit domainId to use your organization's default domain. Optional fields mirror the portal's create form: shortCode, channel, UTM fields (utmSource, utmMedium, utmCampaign, utmTerm, utmContent), fallbackUrl, OG tags (og.title, og.description, og.imageUrl), title, tags, expiry, templateId, params.

Returns 201 with the created link, including its id and the resolved short URL.

List links

curl "https://<your-optolink-host>/links?page=1&limit=20&isActive=true" \
  -H "Authorization: Bearer opl_api_…"

Query	Default	Notes
page	1	1-based
limit	20	Max 100
isActive	all	true or false

Returns 200 with a paginated body: { data: [...], total, page, limit }.

Update a link

PATCH /links/:id accepts the same optional fields as create. Returns 200 with the updated link, 404 if the ID isn't in your organization.

Delete a link

DELETE /links/:id returns 200 on success, 404 if not found. Deletion is permanent — resolution stops immediately.

QR codes

GET /links/:id/qr.svg and GET /links/:id/qr.png return the QR image for the link's short URL with the matching Content-Type. Use these to regenerate QR assets after rotating artwork without re-creating the link.

Errors

Status	code	When
400	—	Validation error (bad field, unknown channel, malformed UUID)
401	—	Missing/invalid key, or organization suspended
402	QUOTA_EXCEEDED	Link quota for your plan reached (quota: "links" in the body)
403	—	Wrong key tier for the route
404	—	Link or domain not in your organization
428	APP_CONFIG_REQUIRED	No app config registered — set up your app first

Rate limits apply per key: reads and QR generation use the resolution-tier limit, writes the creation-tier limit (see Rate limits & errors).