Getting started with the go.uk.app API

Use the API to connect your own application to your links. Each integration gets a separate token with explicit permissions and an expiration date. The API is currently available without a paid subscription; account capacity and request limits still apply.

Create a token with the right permissions

Sign in to API access, give the token a recognizable name, select permissions and choose its validity period. Copy the token immediately: its full value is shown only once.

links:read lists and reads your links.
links:write creates links and edits their destinations, titles or folders.
stats:read reads your link statistics.

Grant only the permissions the integration uses. Store the token on your server as a secret, not in browser JavaScript, screenshots or a public repository.

Make a read request

In the examples below, GO_API_TOKEN is an environment variable containing your token. Do not use your account password or a YOURLS administrator key.

curl --fail-with-body \
  -H "Authorization: Bearer $GO_API_TOKEN" \
  https://go.uk.app/api/v1/links/

The response contains links and a next_after cursor. If the cursor is not null, request the next page with ?after=CURSOR. Requests are restricted to the token owner’s account.

Create a short link safely

curl --fail-with-body https://go.uk.app/api/v1/links/ \
  -H "Authorization: Bearer $GO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: guide-example-001" \
  --data '{"destination":"https://example.com/","title":"API example"}'

Use a new idempotency key for each intended new link. If the connection drops, retry with the same key and identical JSON body. A new key can create another link. The example key is a placeholder, not a value to reuse for every request.

Handle responses and retries

201 means a link was created; 200 can indicate a completed replay. For 202, retry the same operation later. Check the JSON error for 409, which can indicate a conflict or quota limit. 401 means the token is invalid; 403 indicates missing access. Back off on 429 instead of retrying in a tight loop.

Revoke or replace a token

Revoke an unused token on the API page. Replace a leaked token in the integration and revoke the old one. Tokens also stop working after expiration or an account password change. For WordPress, download the plugin from the API page and configure it under Tools → go.uk.app Links with read and write permissions.