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.

Tip: Leave accessToken empty initially. The auth request’s Tests script writes data.accessToken into the collection variable automatically. Every other request uses Authorization: Bearer {{accessToken}}.

For the same flow in GitHub Actions / shell CI, see Mint from CI.

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. On success, accessToken is set for you.

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

Every other request (URLs, QR Codes, Webhooks, …) is now authenticated.

4. Try it — create a short URL

With accessToken set, open URLs → POST /api/v1/urls and click Send. The default body mints on the platform domain (shr.so). Add customSlug and/or domainId when you need a branded host.

{
  "targetUrl": "https://example.com/hello-from-postman",
  "title": "Postman smoke link"
}

Successful response (collection variables id, shortUrl, and shortCode are updated automatically):

{
  "success": true,
  "data": {
    "id": "12345",
    "shortCode": "abc123",
    "shortUrl": "https://shr.so/abc123",
    "targetUrl": "https://example.com/hello-from-postman"
  }
}

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