The API behind
your operations.

01 / Get started

Make your first request

Use your assigned app origin, not this documentation subdomain. Paths already include /api; do not add it twice. This public health check needs no credentials.

curl --fail-with-body \
  -H 'Accept: application/json' \
  'https://waystestar.com/api/health'

The health response includes status, database, scheduler and timestamp. HTTP 503 means the database is unavailable. A degraded response can have HTTP 200 when a scheduler task has failed.

Read company data

1. Have your administrator provision an active staff account for the correct company.
2. Sign in to WaysteStar through Clerk.
3. Use a current session token and an endpoint your account can view.

# WAYSTESTAR_SESSION_TOKEN is your short-lived staff session token.
# Set it locally; never commit or share it.
curl --fail-with-body \
  -H "Authorization: Bearer $WAYSTESTAR_SESSION_TOKEN" \
  -H 'Accept: application/json' \
  'https://waystestar.com/api/customers?limit=25&offset=0'

Expect a JSON array of customer records. Examples use the default app origin; substitute your assigned origin when different. All examples here are reads.

02 / Identity

Authenticate as staff

Staff API requests use Clerk authentication. Same-origin requests from the signed-in app use the browser session. For an authorized client, obtain a short-lived session token through Clerk and send Authorization: Bearer <session-token>.

// Inside an authenticated WaysteStar React component:
// const { getToken } = useAuth(); // from @clerk/react
const token = await getToken();
if (!token) throw new Error('Sign in to WaysteStar first');
const response = await fetch('/api/customers?limit=25', {
  headers: { Authorization: `Bearer ${token}` },
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const customers = await response.json();

Obtain a fresh token when needed. A Clerk secret key is a server credential and must never be used as a staff session token. The documentation site does not accept credentials or execute requests against your account.

Cross-origin browser requests also depend on the app’s allowed origins and cookie policy; hosting documentation separately does not grant API access. For authentication behavior, see Clerk’s authenticated request guide.

03 / Access

Company and permissions

The server resolves your company from your authenticated staff identity. Supplying a tenant ID in a query or header does not authorize access to another company. Record IDs are meaningful within your authorized company.

The endpoint reference lists the relevant section. Unmapped routes deny non-admin access unless a specific self-service rule applies. Some routes require admin access even when you can view the surrounding section. Inactive accounts and unprovisioned users can receive HTTP 403.

04 / Read patterns

Read a page, or read a day

Endpoints using the shared pagination helper accept limit and offset. The default limit is 500, the maximum is 500, and the default offset is zero. Use positive integer limits and non-negative integer offsets. Not every list endpoint uses this helper.

For bare-array lists, advance offset by the number of returned rows until a page is shorter than the requested limit. Concurrent changes can shift offset-based pages; these reads are not a snapshot export.

GET /api/customers/directory returns { rows, total, limit, offset } and applies search and filters before paging. GET /api/routes does not use the shared pagination helper.

05 / Recovery

Handle errors and rate limits

Most JSON errors contain message. Responses vary by endpoint; there is no universal error envelope. Unknown API paths return JSON 404 after authentication checks.

Verified staff requests use a per-user allowance of 600 requests per minute. Anonymous and public-route traffic uses an IP allowance of 500 requests per 15 minutes. Individual endpoints may enforce tighter limits. The client-errors endpoint uses its own limiter.

{
  "code": "RATE_LIMITED",
  "message": "Requests are temporarily limited. Please wait a moment and try again.",
  "retryAfterSeconds": 60
}

This is an illustrative 429 body; the wait value varies. Prefer the Retry-After header. Retry reads conservatively with jitter. Do not blindly retry payment, billing, dispatch or other writes after an ambiguous failure; a global idempotency-key contract is not documented.

06 / Other authentication lanes

Portals and integrations

Customer portal

Customer portal routes use their own access guards. When the deployment uses Clerk portal authentication, customers verify an email or phone contact through Clerk; the server checks that the verified contact can access the account identified by the portal link. A staff session does not automatically grant customer portal access.

In the legacy OTP session mode, the magic-link flow creates a pending session, OTP confirmation activates it, and an HTTP-only portal cookie carries the session. Pending sessions last five minutes; active sessions have a sliding 30-minute lifetime. Sensitive actions can rotate the session. Use the sign-in flow presented by the app rather than assuming either mode is available.

Driver tablets

Driver access uses enrolled devices and driver PINs, followed by an HTTP-only driver session cookie. Shift sessions last 16 hours. Device enrollment determines the company; the driver lane does not use staff Clerk login.

Connected services and webhooks

Payment, telematics and communication integrations are configured through the app. Provider callback routes serve those integrations; their presence is not an outbound event-subscription API. For a new integration, contact support to agree on credentials, supported operations, data ownership and retry behavior before building.

07 / Reviewed operations

Endpoint reference

These read operations were checked against their handlers. The OpenAPI download covers this selection. Record schemas remain open because a complete field-level contract has not yet been published.

08 / Keep in touch

Compatibility and support

The current app uses unversioned /api/ paths. This documentation’s review date is not an API version or compatibility guarantee. Unknown response fields should be tolerated. Coordinate integrations before depending on undocumented fields or write behavior.

For help, email support@waystestar.com with the HTTP method, path, timestamp, status and a sanitized error message. Omit session tokens, cookies, payment details and customer data.

Documentation release · 11 October 2026

Initial developer site: staff access, permission boundaries, pagination exceptions, rate-limit recovery, nine reviewed read operations.