Public read API

Authentication

Pass your API key in the Authorization header. Generate keys from the API Keys settings page. Keys look like sk_live_….

curl https://stagecraft.gg/api/v1/listings?limit=5 \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx"

Rate limiting

Each request returns standard headers so you can pace yourself:X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. When you exceed your quota you get a 429 with a Retry-After header.

Endpoints

Webhooks

Subscribe a URL to receive real-time events when listings change. Each delivery includes an HMAC-SHA256 signature so you can verify Stagecraft sent it. Available event types: listing.created, listing.removed, price.changed, sale.event.

curl -X POST https://stagecraft.gg/api/v1/webhooks \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.example.com/hooks/stagecraft",
    "event_types": ["price.changed", "listing.created"]
  }'

Verifying signatures

Every POST to your webhook URL carries two headers: X-Stagecraft-Timestamp (unix seconds) and X-Stagecraft-Signature (format t=<ts>,v1=<hex>). Compute HMAC_SHA256(secret, "{ts}.{raw_body}") and compare in constant time. Reject if the timestamp is more than 5 minutes off.

// Node.js receiver
import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(rawBody, header, secret) {
  const m = /^t=(\d+),v1=([a-f0-9]+)$/.exec(header || '');
  if (!m) return false;
  const ts = Number(m[1]);
  if (Math.abs(Date.now() / 1000 - ts) > 300) return false;
  const expected = createHmac('sha256', secret)
    .update(`${ts}.${rawBody}`).digest('hex');
  const a = Buffer.from(m[2]);
  const b = Buffer.from(expected);
  return a.length === b.length && timingSafeEqual(a, b);
}

Respond with any 2xx within 10 seconds. Non-2xx responses are retried with exponential backoff; subscriptions disable themselves after sustained failures.

Response shape

Every successful response wraps the payload in a data field:

{
  "data": [ ... ],
  "pagination": { "total": 487, "limit": 50, "offset": 0, "has_more": true }
}

Errors use a consistent shape:

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry in 17s.",
    "retry_after": 17
  }
}

Compliance

The API exposes the same public data the marketplace already publishes — never paid asset files, never buyer emails, never login-walled content. Don't redistribute bulk listing dumps; that violates Cfx PLA §3.1(6) and your Terms of Service. If you need a bulk export for analysis, email help@stagecraft.gg.

Versioning

The API is versioned in the URL (/v1/…). Breaking changes ship as /v2/… with overlap; v1 stays available for at least 12 months after v2 GA.