REST API Overview

REST / JSON

The PaceCast REST API enables programmatic management of client workspaces, ad data ingestion, campaign diagnostics, content drafting, and credit balances.

Last updated: October 2026

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/api

Local development environments default to http://localhost:3000/api.

Authentication Headers

Header NameTypeUsage & 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 StatusTypeMeaning & 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.