The PaceCast REST API is organized around predictable resource-oriented URLs, accepts JSON-encoded or multipart request bodies, returns standard HTTP response codes, and delivers JSON-formatted error envelopes.
Base URLs & Protocols
All API requests must be transmitted securely over HTTPS:
Base URL
https://pacecast.app/apiLocal development environments default to http://localhost:3000/api.
Authentication Headers
| Header Name | Type | Usage & Format |
|---|---|---|
Authorizationrequired | Bearer <token> | Standard OAuth 2.1 or Supabase session Bearer JWT. Identifies caller tenant identity via 'sub' claim. |
Content-Typerequired | application/json | Required for JSON payloads. Multipart file uploads use 'multipart/form-data'. |
x-api-keyoptional | string | Service secret key for automated background jobs and internal report rendering. |
Standard JSON Response Envelopes
Successful responses return standard JSON root objects:
Sample Successful Response (200 OK)
{
"client": {
"id": "01934c2b-e104-7da5-b982-b7e61a6c4290",
"name": "NorthStar Athletics",
"currency": "USD",
"timezone": "America/New_York",
"created_at": "2026-10-14T18:24:00.000Z"
}
}Rate Limits & Quotas
To maintain system stability and prevent denial-of-service degradation, PaceCast enforces the following rate limits:
- Authenticated API: 1,200 requests per minute per authenticated user UUID.
- Gift Card Redemption: 5 attempts per hour per user account to prevent brute-force PIN enumeration.
- Public Demo Endpoints: 20 analysis runs per calendar day per IP address.
Error Codes & Status Responses
| HTTP Status | Type | Meaning & Common Cause |
|---|---|---|
400 Bad Requestrequired | Validation Error | Malformed request schema, invalid date range, or CSV header aliasing failure. |
401 Unauthorizedrequired | Auth Error | Missing, invalid, or expired Bearer JWT or session cookie. |
404 Not Foundrequired | Tenant Isolation | Resource does not exist or caller does not own the target workspace. |
429 Too Many Requestsrequired | Rate Limited | Quota exceeded. Respect the Retry-After header before repeating. |