What will the CTAurl API do?
The CTAurl API is not available yet. When it is switched on, it will create short links and QR codes from your own software. It is a small REST API over HTTPS with JSON bodies, at https://app.ctaurl.com/api/v1. Every request will authenticate with a bearer token from your workspace, and these are the requests it will accept:
| Request | What it does |
|---|---|
POST /links | Create a link on a CTA domain or ctaurl.me, with an optional back-half, title, tags and expiry time (expiresAt) |
GET /links/{id} | Read one link |
PATCH /links/{id} | Disable a link ({"disabled": true}) |
POST /qr-codes | Create a QR code for an existing link, or a new link and its QR code in one call |
GET /qr-codes/{id} | Read a QR code |
PATCH /qr-codes/{id} | Change a QR code's colours and style |
GET /qr-codes/{id}/svg, /png | Download the QR code as SVG or PNG |
API tokens and permissions
CTAurl API tokens are made by the workspace owner in the app under Settings → API keys. Each token is either Read only or Manage (read and create). A token is shown once, when it is made, and can be revoked at any time. A workspace can have up to 20 active tokens. Send the token in the Authorization header:
Authorization: Bearer cta_live_…How to create a short link with the API
Once the API is switched on, to create a short link you send POST /links with your bearer token, an Idempotency-Key and a JSON body. Every create request carries an Idempotency-Key: the time in Unix milliseconds, a dot, and a UUID v4. If a request times out, send it again with the same key within 24 hours and you get the original result instead of a second link.
curl https://app.ctaurl.com/api/v1/links \
-H "Authorization: Bearer $CTAURL_TOKEN" \
-H "Idempotency-Key: 1761638400000.7f8c2a54-3b1e-4c6d-9a0f-2e5b8c1d4f60" \
-H "Content-Type: application/json" \
-d '{"domain":"buy-it.now","shortCode":"sneaker","destinationUrl":"https://shop.abc.yz/sneaker"}'A successful request answers 201 with the link, including shortUrl. If you leave out shortCode, a back-half is generated for you. Links made through the API will count towards the same monthly allowance as links made in the app.
Rate limits and errors
The CTAurl API will allow 60 requests a minute per workspace, return errors as JSON with a stable code, and accept requests only on app.ctaurl.com.
- 60 requests a minute per workspace. Over that, the answer is
429withRetry-After. - Errors return JSON:
{"error": {"code": "…", "message": "…"}}with a stable code such asINVALID_REQUEST,FORBIDDEN_SCOPEorRESOURCE_UNAVAILABLE. - Requests are only accepted on
app.ctaurl.com.
What the API does not do yet
Beyond not being switched on yet, the CTAurl API does not list all links, change a link's destination (do that in the app) or return click and scan counts. There are no webhooks and no SDKs, and custom domains are not available. When any of these arrive, this page will say so.
Questions people ask about the API
Does CTAurl have an API?
Not yet. The CTAurl API is built but not switched on. When it is, it will create and read short links and QR codes, disable links, and download QR codes as SVG or PNG, with tokens the workspace owner makes under Settings, API keys. It does not list links, change destinations, return click counts or send webhooks.
Does the CTAurl API have a rate limit?
Yes. Once it is switched on, the CTAurl API will allow 60 requests a minute per workspace. A request over the limit will get a 429 answer with a Retry-After header. Links created through the API will also count towards your plan's monthly link allowance, the same as links made in the app.