A complete link API with safe account boundaries
Create, inspect, update and retire links; download QR codes; configure routing; record outcomes; and deliver signed events from one versioned API.
Request an API key
Your first request
Planning serious volume? Review the free enterprise controls, then use the API product page to plan your integration end to end.
What this means in practice
Controlled API access
Every API account is reviewed first; approved users create and revoke hashed keys from Dashboard Settings.
Full link lifecycle
Create, inspect, update and permanently retire owned links with paginated inventory and safe retries.
Automate smart routing
Configure device, country, experiment, expiration, password, and preview rules for any link the key owns.
Track outcomes
POST idempotent purchases, signups, bookings, or other conversion events against any link you own.
Observable webhooks
Select events, test delivery, inspect errors, replay failures and rotate signing secrets.
Scoped and revocable
Bearer keys are tied to one verified account, stored as hashes, rate-limited, and independently revocable.
MCP for AI workflows
Use the same account boundary through a stateless MCP endpoint with narrowly scoped link and analytics tools.
Request approved API access
Open Dashboard → Settings → API access, describe your server-side use case and expected volume, and submit it for administrator review. Credentials cannot be created or used until the account is approved.
After approval, name a key and copy it once. Send it as Authorization: Bearer gtn_YOUR_KEY. Keys are stored as hashes and can be revoked individually without changing your password. Revoking account-level API approval immediately disables all active credentials.
Public endpoints
| Endpoint | Method | Purpose |
|---|---|---|
/api/v1/links |
GET | Paginate and filter links owned by the key's account |
/api/v1/links |
POST | Create a short link from url and an optional slug |
/api/v1/links/{shortCode} |
GET / PATCH / DELETE | Inspect, update, or permanently retire an owned link |
/api/v1/links/{shortCode}/analytics |
GET | Retrieve aggregate clicks, conversions, routing, and safety state |
/api/v1/links/{shortCode}/qr |
GET | Download a styled PNG or SVG QR code |
/api/v1/links/{shortCode}/routing |
GET / PUT / DELETE | Read, configure, or disable smart routing for an owned link |
/api/v1/conversions |
POST | Attach a purchase, signup, booking, or other outcome to a short code |
/api/v1/slug-suggestions |
POST | Generate readable back-half suggestions from a URL or title |
/api/openapi.json |
GET | OpenAPI 3.1 contract for SDK and automation tools |
/mcp |
POST | Stateless MCP 2026-07-28 tools for links, analytics and slug suggestions |
Create a link
curl https://goto.now/api/v1/links \
-H "Authorization: Bearer gtn_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/launch","slug":"launch"}'
A successful request returns HTTP 201 with shortUrl, shortCode, and an opaque dashboardToken. Add an Idempotency-Key header for safe retries. Creation is limited to 120 requests per minute per key; redirects are not part of that limit.
Configure smart routing
curl -X PUT https://goto.now/api/v1/links/launch/routing -H "Authorization: Bearer gtn_YOUR_KEY" -H "Content-Type: application/json" -d '{"defaultUrl":"https://example.com","iosUrl":"https://apps.apple.com/app/example","countryRules":{"SG":"https://example.com/sg"},"abVariants":["https://example.com/a","https://example.com/b"]}'
The endpoint also accepts androidUrl, mobileUrl, desktopUrl, an ISO 8601 expiresAt plus fallbackUrl, an eight-character-or-longer password, and a preview object with title, description, and image. DELETE restores a direct redirect to the default destination before removing the routing rules.
Record a conversion
curl https://goto.now/api/v1/conversions \
-H "Authorization: Bearer gtn_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"shortCode":"launch","event":"purchase","externalId":"order_123","value":49,"currency":"USD"}'
externalId makes retries idempotent: sending the same identifier with the same key returns the original event instead of double-counting it. Optional metadata may be a JSON object. Conversion creation is limited to 240 requests per minute per key.
Signed webhooks
Add a public HTTPS endpoint in Settings and choose the events it receives. Deliveries come from a durable retry queue and include X-GoTo-Signature, an HMAC-SHA256 signature made with the signing secret shown when the endpoint is created. Settings includes test delivery, delivery history, replay, failure state, and secret rotation.
AI-agent and MCP access
Connect a compatible MCP client to https://goto.now/mcp and use the same Authorization: Bearer gtn_YOUR_KEY account key. The stateless endpoint follows protocol version 2026-07-28 and exposes narrowly scoped tools to create and list links, read aggregate analytics, and suggest readable slugs. It never exposes raw visitor records or another account's inventory.
Errors and key safety
Errors are JSON with an error field and an appropriate 4xx or 5xx status. Keep keys in a server-side secret manager, never browser JavaScript or a public repository. Revoke a key immediately if it is exposed.