API pagination and errors

Authorize and list resources

The management API uses Authorization: Bearer YOUR_API_TOKEN. A token is bound to one workspace and cannot select another workspace per request.

List endpoints for clients, projects, forms and submissions support bounded pagination with limit from 1 to 100 and an opaque cursor. The default limit is 50.

curl -H 'Authorization: Bearer YOUR_API_TOKEN' \
  'https://pantherhook.com/api/v1/forms?limit=25'

Use the next cursor

A list page returns items and nextCursor. When nextCursor is present, make the same authenticated GET request with ?limit=25&cursor=<URL_ENCODED_CURSOR> to fetch the next page.

Treat cursors as opaque values and preserve the same filters and requested page size. A missing next cursor means the result set has no further page.

Example server-side Node.js loop. Keep the token in an environment variable. URLSearchParams safely encodes each opaque cursor; the loop stops when the API returns nextCursor: null.

const endpoint = 'https://pantherhook.com/api/v1/forms';
let cursor;
do {
  const url = new URL(endpoint);
  url.searchParams.set('limit', '25');
  if (cursor) url.searchParams.set('cursor', cursor);
  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.PANTHER_HOOK_TOKEN}` },
  });
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  const page = await res.json();
  for (const form of page.items) console.log(form.id, form.name);
  cursor = page.nextCursor;
} while (cursor);

Recognize API errors

• 401 API_TOKEN_INVALID: credential is absent, expired, revoked or malformed. Issue a valid workspace API token.
• 403 API_SCOPE_REQUIRED: add only the scope needed for the endpoint.
• 429 API_RATE_LIMITED or API_AUTH_RATE_LIMITED: back off and retry within the documented limits.
• Other errors may indicate invalid DTO fields, missing resources or plan restrictions. Inspect statusCode, code and message without leaking sensitive values.
• Example of the stable structured fields for an API-token authentication failure. The exact message varies by failure.

{
  "statusCode": 401,
  "code": "API_TOKEN_INVALID",
  "message": "Invalid or expired API token"
}

Use the machine-readable contract

For field-level DTOs, current operations and exact response schemas, download the OpenAPI specification rather than assuming one example documents every case.