​

Conventions

​

Versioning

Scripe-Api-Version: 2026-08-10

• Accepted versions, newest first:

  Version	What changed
  2026-08-10	Current, and the default. Read scopes are enforced: GET notes/posts require notes:read / posts:read, GET /sources/{id} requires sources:read, and POST /uploads requires sources:write or knowledge:write — the scopes this documentation always listed, now checked. A <resource>:write scope satisfies the read requirement. Failing requests get 403 scope_missing with the fix in the message.
  2026-08-01	Deprecated, sunset 2026-11-15. The four gated reads above — GET notes/posts (collection and item), GET /sources/{id}, and POST /uploads — accept any valid token of the workspace. Every other endpoint enforces its scope on this version exactly as on the current one, so pinning it is not a general escape hatch. Still served until sunset, but re-mint the key rather than relying on it.

• Omitted header → we default to the current version. Fine for exploration, dangerous in production — pin explicitly so the next version cut doesn’t change your responses under you.
• Unknown version → 400 version_unsupported. The error message lists the versions we still accept.
• We accept at least the two most recent versions at any time, with a minimum 90-day overlap when we sunset an old one. Sunset is announced via response headers long before the version stops being served:

Scripe-Api-Version: 2026-08-01
Scripe-Deprecation: true
Sunset: Sun, 15 Nov 2026 00:00:00 GMT

​

Pagination

​

Request

GET /v1/notes?projectId=proj_abc&limit=50
GET /v1/notes?projectId=proj_abc&limit=50&cursor=<prev next_cursor>

​

Response envelope

{
  "data": [ /* resource objects */ ],
  "pagination": {
    "next_cursor": "eyJjcmVhdGVkQXQiOiIyMDI2L…",
    "has_more": true,
    "total": 128
  }
}

• next_cursor is null once there are no more rows.
• has_more is the canonical “loop again?” signal. Don’t compare cursor values — they’re opaque and may change shape across versions.
• total is optional and currently ships on /posts and /notes only — see Counting without paging.
• A cursor is bound to the request’s filter set. Changing projectId, dateFrom, dateTo, status, folderId, etc. mid-loop will likely emit 400 bad_cursor because the keyset reference no longer applies.
• A cursor never expires server-side, but your filters might (e.g. you filter by a dateTo that’s now in the past). Treat 400 bad_cursor as “start the loop over from the beginning” rather than as a bug.

​

Counting without paging

GET /v1/posts?projectId=proj_abc&status=draft&limit=1
→ { "data": [ … 1 row … ],
    "pagination": { "has_more": true, "total": 128 } }

​

Large text fields in a list

GET /v1/posts?projectId=proj_abc
→ { "data": [ { "content": "The junior developer role is dying and here is…",
                "contentTruncated": true, … } ] }

• The single-resource read (GET /v1/posts/{postId}) always serves the whole field, with the flag false.
• ?content=full returns whole bodies for a page; ?content=none omits them. Both are on GET /v1/posts and GET /v1/analytics/posts with the same spelling and the same preview default.
• A shortened field is never served without its flag. Without one, a client cannot tell an excerpt from the resource, which is how clipped text ends up quoted back to a user as something they wrote.
• When you also pass q, the excerpt is centred on the first matching term, so a row shows why it matched.

​

Pagination idiom (pseudocode)

let cursor: string | null = null;
while (true) {
  const u = new URL("https://api.scripe.io/v1/notes");
  u.searchParams.set("projectId", projectId);
  u.searchParams.set("limit", "100");
  if (cursor) u.searchParams.set("cursor", cursor);
  const res = await fetch(u, { headers });
  const { data, pagination } = await res.json();
  yield* data;
  if (!pagination.has_more) break;
  cursor = pagination.next_cursor;
}

​

Offset pagination

{
  "data": [ /* post analytics */ ],
  "pagination": { "total": 412, "limit": 50, "offset": 100, "has_more": true }
}

​

Errors

{
  "error": {
    "code": "key_revoked",
    "message": "This API key has been revoked.",
    "request_id": "req_01J9Z…",
    "docs_url": "https://docs.scripe.io/api/v1/errors#key_revoked"
  }
}

• code is the canonical machine-readable identifier. Stable across releases. Switch on this — never on message or HTTP status alone.
• message is human-readable and may evolve. It states what to do differently, not just what went wrong.
• request_id is your handle to correlate with our tracing if you open a support ticket. It also matches the X-Request-Id response header.
• docs_url deep-links to the entry for the code in the error reference.
• details (optional) carries a code-specific payload — e.g. spend_cap_exceeded includes the cap and current spend, and scope_missing includes required_scope when it comes from a handler-level or MCP check (the route-level guard behind most REST 403s sends no details). Always fall back to message.

{
  "error": {
    "code": "not_found",
    "message": "Idea \"idea_9f2c\" was not found in project \"proj_a1b2\". It may have been deleted, or it belongs to a different project — re-resolve the id by listing ideas for this project.",
    "details": { "resource": "idea", "id": "idea_9f2c", "projectId": "proj_a1b2" }
  }
}

​

Status code summary

​

Rate limits

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded for writes (30 per minute). Retry after 21s.",
    "details": { "retryAfterSeconds": 21, "limit": 30, "bucket": "write" }
  }
}

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 41

HTTP/1.1 429 Too Many Requests
Retry-After: 17
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 17

​

Survival tips

• Pre-throttle. Watch Remaining and slow yourself down rather than burning the whole budget.
• Respect Retry-After. It’s the smallest safe sleep value; longer is fine.
• Buckets are independent. A write 429 doesn’t stop you reading — keep answering questions while you pace the mutations.
• Budget is per credential. Each key and each OAuth grant carries its own bucket, so a CI loop on its own key can’t throttle your production integration. That is not licence to shard around the limit: the workspace-level caps (job concurrency, plan usage) still apply.
• Prefer webhooks over polling. A webhook endpoint on job.completed / post.created removes most polling loops entirely.
• Test mode counts. A test key has its own bucket but hits the same production data — CI loops shouldn’t run against production data without a dedicated test workspace.

​

Headers we set on every response

Scripe-Api-Version: 2026-08-10
X-Request-Id: req_01J9Z…
Access-Control-Allow-Origin: *
Cache-Control: no-store        (default; health probes override)

​

Resource IDs

​

Date and time

2026-08-01T14:23:11.000Z

​

CORS

​

Anything else?