Postman Collection

The Shortnd public API ships with a Postman collection that mirrors every /api/v1 route — 33 requests across Auth, API Keys, Domains, URLs, QR Codes, Analytics & Usage, Webhooks — plus the body schemas and example payloads. Use it for one-off exploration, repeatable smoke tests, or as the canonical reference next to your own SDK.

1. Import the collection

The collection is a single JSON file (public-api.postman_collection.json, ~24 KB).

Postman desktop or web:

1. Open Postman.
2. Click File → Import (desktop) or the Import button at the top of the workspace (web).
3. Drop the downloaded file into the dialog, or paste this URL:

https://docs.shortnd.com/public-api.postman_collection.json

Postman will create a new collection named Shortnd Public API with seven folders matching the API resources.

2. Set the collection variables

Open the new collection's Variables tab. Three of these are wired by default; fill in the rest before sending requests.

Variable	Default	What it is
baseUrl	https://shortnd.com	API origin. Override to http://localhost:7777 for local dev.
apiKey	empty	Long-lived API key minted from the dashboard (how to). Format: snd_live_xxx.yyy.
accessToken	empty	Short-lived bearer token (15 min). Set this from the response of the auth request below.
organizationId	empty	Your tenant org id. Visible in the dashboard URL.
domainId	empty	Custom domain id when creating links on a branded host.
id	empty	Generic single-resource id (URL id, webhook id, etc.).
qrId	empty	QR code id (UUID) when working with a single QR record.

Tip: Leave accessToken empty initially. After the first auth request runs, paste the returned accessToken into this variable — every other request reads it as Authorization: Bearer {{accessToken}}.

3. Mint your first bearer token

Open Auth → POST /api/v1/auth/token and click Send. The request uses Authorization: ApiKey {{apiKey}} and returns a 15-minute bearer token.

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 900,
    "scopes": ["urls:read", "urls:write", "domains:read", ...]
  }
}

Copy data.accessToken and paste it into the accessToken collection variable. Every other request (URLs, QR Codes, Webhooks, …) is now authenticated.

Faster workflow: drop this snippet into the auth request's Tests tab and Postman will set the variable automatically:

const body = pm.response.json();
pm.collectionVariables.set('accessToken', body.data.accessToken);

4. Try it — create a short URL

With accessToken set, open URLs → POST /api/v1/urls and click Send. The default body creates a link on a custom domain — adjust the domainId (or remove it for the platform domain) and hit Send.

{
  "targetUrl": "https://example.io/onboarding",
  "customSlug": "welcome",
  "domainId": "{{domainId}}"
}

Successful response:

{
  "success": true,
  "data": {
    "id": "12345",
    "shortCode": "abc123",
    "targetUrl": "https://example.io/onboarding",
    ...
  }
}

5. Stay in sync

The collection is regenerated alongside every API change in the shortnd-frontend repo at public-api.postman_collection.json. The download link on this page always points at the latest version — re-import it whenever you upgrade your SDK or want a new endpoint.

For the canonical contract (request/response schemas, error codes), the OpenAPI spec is the source of truth; the Postman collection mirrors it.

Troubleshooting

Symptom	Fix
401 Unauthorized on /api/v1/auth/token	Check the apiKey variable — must be the full snd_live_xxx.yyy string, no quotes.
403 Forbidden on a URL/QR/domain request	Bearer token expired (15 min lifetime) — re-run the auth request.
404 Not Found for an id you just created	Verify the id / qrId variable was updated; Postman keeps stale values across requests.
429 Too Many Requests	You've hit the per-key rate limit (details). Wait or rotate to a higher-quota tier.
Domain not found on bulk URL create	The domainId references a domain that isn't active for your org — verify with GET /api/v1/domains.