Response envelopes
Single resources return { data, meta }. Collections return { data, page, meta }. meta.correlationId is the request's trace id — include it when contacting support.
{
"data": [ { "object": "client", "id": "…" }, … ],
"page": { "cursor": null, "nextCursor": "eyJ…", "hasMore": true },
"meta": { "correlationId": "c-…" }
}Pagination
Lists use keyset (cursor) pagination — stable under inserts and fast at any depth. Pass limit (1–100) and the nextCursor from the previous page as cursor. Iterate until hasMore is false.
curl "https://api.skedcast.com/v1/posts?limit=50&cursor=eyJ…" \
-H "Authorization: Bearer sked_live_YOUR_KEY"Idempotency
Every POST must carry an Idempotency-Key header (any unique string — a UUID is ideal). Replaying the same key returns the original result instead of creating a duplicate, so a network retry is always safe.
Standard headers
| Header | Direction | Purpose |
|---|---|---|
Authorization | request | Bearer sked_… (API key) or Bearer <token> (OAuth) |
Idempotency-Key | request | Required on POST; dedupes retries |
X-Correlation-Id | both | Trace id; echoed in meta.correlationId |
RateLimit-* | response | Remaining quota + reset (on throttle: Retry-After) |
Errors
Errors are RFC 9457 application/problem+json. Every error carries a stable machine code, an HTTP status, a human title/detail, and the correlationId. Validation failures (422) add a per-field errors array.
{
"type": "https://docs.skedcast.com/errors/validation_failed",
"title": "Validation failed",
"status": 422,
"category": "bad-body",
"code": "validation_failed",
"detail": "One or more fields are invalid.",
"correlationId": "c-…",
"errors": [ { "path": "content", "message": "Required" } ]
}Status codes
| Status | Meaning |
|---|---|
| 400 / 422 | Malformed request / validation failed |
| 401 | Missing or invalid credentials |
| 403 | Authenticated but lacking the scope/role |
| 404 | Resource not found |
| 409 | Conflict (idempotency or state) |
| 429 | Rate limited — back off per Retry-After |
| 5xx | Transient/server error — safe to retry |
FAQ
- Why keyset pagination instead of page numbers?
- Keyset (cursor) pagination is stable when rows are inserted or deleted mid-iteration and stays fast at any depth, unlike offset pagination. Just follow nextCursor until hasMore is false.