Authentication
Use the production base URL https://goto.now. Send your account key in every request as Authorization: Bearer gtn_YOUR_KEY. Keep the key on your server; never embed it in browser JavaScript, a mobile application, a public repository, or a URL.
Authorization: Bearer gtn_YOUR_KEY
Content-Type: application/json
Endpoints
| Method | Endpoint | Purpose |
|---|---|---|
| POST | /api/v1/stay-safe | Create a protected page |
| GET | /api/v1/stay-safe?page=1&limit=25 | List owned pages; limit is 1–100 |
| GET | /api/v1/stay-safe/{slug} | Read one owned page and its destinations |
| PATCH | /api/v1/stay-safe/{slug} | Update protection, metadata, or destinations |
| DELETE | /api/v1/stay-safe/{slug} | Retire the public page |
Create a protected page
Supply 1–200 items on a standard account, or up to the approved value in X-Stay-Safe-Page-Link-Limit. An item can be a URL string or an object containing a URL and display label. Add an Idempotency-Key of 8–110 letters, numbers, dots, underscores, colons, or hyphens when a request may be retried.
curl https://goto.now/api/v1/stay-safe \
-H "Authorization: Bearer gtn_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: external-site-order-1042" \
-d '{
"slug": "order-1042-files",
"title": "Order 1042 files",
"description": "Documents shared by our support team",
"password": "use-a-long-separate-password",
"captchaType": "cool",
"individualLinks": true,
"proceedStep": true,
"provider": {
"name": "Example Store",
"url": "https://store.example"
},
"items": [
{"label": "Invoice", "url": "https://files.example/invoice.pdf"},
{"label": "Manual", "url": "https://files.example/manual.pdf"}
]
}'
Request fields
| Field | Required | Rules |
|---|---|---|
items | On create | Array of URL strings or {label,url} objects: 1–200 standard, or the account's approved per-page limit. Supplying it during PATCH replaces the entire list and resets item IDs and click counts. |
slug | No | 3–64 lowercase letters, numbers, underscores, or hyphens. A random slug is generated when omitted. |
title | No | 2–120 characters; defaults to Protected links. |
description | No | Up to 500 characters. |
password | No | 8–300 characters. It is hashed and is never returned. |
captchaType | No | none, cool, basic, turnstile, hcaptcha, or simple. |
individualLinks | No | Boolean; show a separately tracked button for each destination. |
proceedStep | No | Boolean; show an acknowledgement screen before the access gate. |
active | No | Boolean; defaults to true. |
provider | No | Object with optional name and public HTTP(S) url. |
CAPTCHA behavior
cool, basic, and simple are built into GoTo.now. turnstile and hcaptcha use GoTo.now's configured provider integration and return HTTP 400 if that provider is unavailable. Your calling site never sends or receives CAPTCHA provider secrets.
Capacity and abuse limits
Standard capacity is 1–200 destinations per protected page, 10,000 destinations across active Stay Safe pages, and 60 API requests per minute per account. Retired or inactive pages do not consume stored-link capacity. Approved increases are account-wide and automatically apply to every active key.
Request more capacity from Dashboard → Settings → API access → Stay Safe API capacity. Enter the page size, active-link capacity, request rate, and workload justification. The dashboard shows pending and approved status; administrators review requests before the new limits take effect.
The request allowance is shared by all account keys so additional keys cannot bypass it. Referral capacity rewards may also raise that allowance. Every authenticated Stay Safe response advertises the effective values in X-Stay-Safe-Page-Link-Limit, X-Stay-Safe-Account-Link-Limit, X-RateLimit-Limit, and X-RateLimit-Policy. When traffic exceeds the rate, the API returns HTTP 429 with code: rate_limit_exceeded, a human-readable message, and Retry-After. Pause for the stated interval and retry with jitter.
A request that would exceed stored-link capacity returns HTTP 429 with code: account_link_quota_exceeded plus limit, used, requested, and remaining. Retire an unused page or submit fewer links before retrying.
201 response
{
"id": 42,
"slug": "order-1042-files",
"publicUrl": "https://goto.now/stay-safe/order-1042-files",
"title": "Order 1042 files",
"description": "Documents shared by our support team",
"provider": {"name": "Example Store", "url": "https://store.example"},
"captchaType": "cool",
"passwordProtected": true,
"individualLinks": true,
"proceedStep": true,
"active": true,
"views": 0,
"unlocks": 0,
"items": [
{"id": 91, "label": "Invoice", "url": "https://files.example/invoice.pdf", "clicks": 0}
]
}
When an idempotent response is replayed, the API also sends Idempotency-Replayed: true.
Server-side JavaScript example
const response = await fetch("https://goto.now/api/v1/stay-safe", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.GOTO_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": `stay-safe-${order.id}`
},
body: JSON.stringify({
title: `Files for order ${order.id}`,
captchaType: "cool",
items: order.files.map(file => ({ label: file.name, url: file.url }))
})
});
if (!response.ok) throw new Error(`GoTo.now returned ${response.status}`);
const protectedPage = await response.json();
console.log(protectedPage.publicUrl);
Update, remove a password, or retire
# Change metadata without replacing items
curl -X PATCH https://goto.now/api/v1/stay-safe/order-1042-files \
-H "Authorization: Bearer gtn_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"title":"Updated order files","captchaType":"basic"}'
# Remove the existing password
curl -X PATCH https://goto.now/api/v1/stay-safe/order-1042-files \
-H "Authorization: Bearer gtn_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"clearPassword":true}'
# Retire the page; success returns HTTP 204
curl -X DELETE https://goto.now/api/v1/stay-safe/order-1042-files \
-H "Authorization: Bearer gtn_YOUR_KEY"
Errors and operational rules
| Status | Meaning |
|---|---|
| 400 | Invalid JSON, fields, URLs, item count, password, CAPTCHA selection, or idempotency key. |
| 401 | Missing, invalid, revoked, unapproved, blocked, or unverified API credential. |
| 404 | The slug does not belong to the API key's account. |
| 409 | The requested slug is invalid or already in use. |
| 429 | The account exceeded 60 requests per minute, its active-link quota, or has another write in progress. Inspect code and honor Retry-After when present. |
Destination URLs are decrypted only for authenticated owner API responses and after a visitor passes the public gate. Public pages use private, no-store responses and one-hour browser grants. Rotate or revoke a credential immediately from Dashboard → Settings → API access if it is exposed.
Machine-readable contract
Import https://goto.now/api/openapi.json into an OpenAPI 3.1 client, Postman, Zapier, Make, or another automation platform. The schema is the machine-readable companion to this guide.