THIS WEEK The Essential Guide to URL Management Read this week's article →
All API references

Stay Safe API

Create and manage protected pages containing up to 200 encrypted-at-rest destinations from another server.

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

MethodEndpointPurpose
POST/api/v1/stay-safeCreate a protected page
GET/api/v1/stay-safe?page=1&limit=25List 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

FieldRequiredRules
itemsOn createArray 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.
slugNo3–64 lowercase letters, numbers, underscores, or hyphens. A random slug is generated when omitted.
titleNo2–120 characters; defaults to Protected links.
descriptionNoUp to 500 characters.
passwordNo8–300 characters. It is hashed and is never returned.
captchaTypeNonone, cool, basic, turnstile, hcaptcha, or simple.
individualLinksNoBoolean; show a separately tracked button for each destination.
proceedStepNoBoolean; show an acknowledgement screen before the access gate.
activeNoBoolean; defaults to true.
providerNoObject 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

StatusMeaning
400Invalid JSON, fields, URLs, item count, password, CAPTCHA selection, or idempotency key.
401Missing, invalid, revoked, unapproved, blocked, or unverified API credential.
404The slug does not belong to the API key's account.
409The requested slug is invalid or already in use.
429The 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.


Return to all API references