Server links

Manage production links with a server key. All reads and writes are scoped to that key's workspace. MCP's optional link-management tools use the same validation and ownership rules.

Create a link

curl --fail-with-body https://api.linkrunway.com/v1/server/links \
  -H "Authorization: Bearer $LINKRUNWAY_SERVER_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"key":"summer-example","title":"Summer example","url":"https://example.com/summer","campaign":"summer","tags":["docs-example"]}'

Required fields are key, title, and url. The response includes the link, shortUrl, and duplicate. Save the returned id for subsequent reads and updates.

Field	Accepted value
`key`	3–60 characters; letters, digits, underscore, or hyphen
`title`	Trimmed string, 1–120 characters
`url`	HTTP or HTTPS URL, at most 2,048 characters, no embedded credentials
`domainId`	Verified domain ID belonging to this workspace; nullable
`iosUrl`, `androidUrl`	Optional platform destinations with the same URL validation; nullable
`appPath`	At most 500 characters, beginning with `/`; nullable
`partnerId`	Active partner in this workspace; nullable
`campaign`, `source`, `medium`	At most 120 characters each; nullable
`tags`	Up to 10 trimmed strings of 1–30 characters; defaults to `[]`
`metadata`	Flat metadata object; defaults to `{}`; see API conventions
`expiresAt`	ISO UTC timestamp; nullable

A key is unique within the workspace. An identical normalized creation retry returns the existing link with duplicate: true. Reusing a key with different data, or reusing an archived key, returns 409. Use a stable key from your own record and persist it before sending the request.

List and read

curl --fail-with-body 'https://api.linkrunway.com/v1/server/links?page=1&limit=20&search=summer' \
  -H "Authorization: Bearer $LINKRUNWAY_SERVER_KEY"

curl --fail-with-body "https://api.linkrunway.com/v1/server/links/$LINK_ID" \
  -H "Authorization: Bearer $LINKRUNWAY_SERVER_KEY"

List returns { items, total, page, limit }, ordered by creation time descending with an ID tie-breaker. page is 1–10,000 (default 1), limit is 1–100 (default 20), and search is at most 100 characters. Search matches title, key, and destination without case sensitivity. Inspect archived on returned items; the list is not limited to active links.

Reading an unknown ID or one from another workspace returns 404. A list is paginated, not a snapshot: new writes can change page boundaries while you iterate.

Update or archive

curl --fail-with-body -X PATCH "https://api.linkrunway.com/v1/server/links/$LINK_ID" \
  -H "Authorization: Bearer $LINKRUNWAY_SERVER_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"url":"https://example.com/new-destination","tags":["updated"]}'

Updates accept the creation fields as optional fields, plus archived: boolean. Omitted fields stay unchanged. Set supported nullable fields to null to clear them; set tags: [] or metadata: {} to replace them with empty values. Collections are replaced, not merged.

Archive with {"archived":true} and restore with {"archived":false}. There is no public DELETE route in this API.

Changes can affect already-distributed URLs and QR codes. Changing the key changes the path; do not assume the old key continues to resolve. Review routing and partner changes before applying them, then test the returned shortUrl.

Common failures

400 means invalid input or an unusable domain/partner relation. 401 means the credential is invalid. 403 means a publishable key was used where a server key is required. 402 indicates a plan allowance. 404 hides missing and cross-workspace links. 409 indicates conflicting key reuse.