Skip to main content

Documentation Index

Fetch the complete documentation index at: https://apidocs.scripe.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Scripe API v1

Status: Public preview. v1 covers the Phase 2 read surface, the Phase 3 Slice A sync writes (notes, posts, sources/text), the Slice B async-job surface (POST /v1/posts/generations + the /v1/jobs family), and the Wave 4 file-ingest surface (POST /v1/uploads, POST /v1/knowledge, POST /v1/sources with type: "file"). We follow Scripe’s deprecation policy — breaking changes only ship in a new dated version with at least 90 days of overlap.
The Scripe API is a JSON REST API for reading and writing the same workspace data the Scripe dashboard does. The current release ships the read surface, synchronous writes (notes, posts, text sources), the async-job surface for AI post generation, and file ingestion for sources and the knowledge base. Webhooks land in the next slice. If you’d rather drive Scripe via an MCP-compatible client (Claude Desktop, Cursor, ChatGPT, agent frameworks), see mcp.md. For multi-tenant integrations that need OAuth on behalf of a Scripe user, see oauth.md. The semantics under the hood are identical across REST + MCP.

​
TL;DR

# 1. Mint a key in the dashboard (Settings → Developer → API keys).
# 2. Sanity-check it.
curl -i https://api.scripe.io/v1/workspaces/me \
  -H "Authorization: Bearer scripe_sk_live_…" \
  -H "Scripe-Api-Version: 2026-08-01"
A 200 OK with your workspace’s id, plan and the principal info confirms the key works. A 401 means re-mint or check the header. A 403 means your plan does not include API access — upgrade to Advanced or Business.

​
Base URL

https://api.scripe.io/v1
The REST API is served from the dedicated api.scripe.io host. The MCP transport lives on https://mcp.scripe.io/api/mcp — see mcp.md.

​
Authentication

Authorization: Bearer scripe_sk_live_…
Every request must carry a Bearer token in the Authorization header. Two flavours are supported:
  • Personal Access Token (single-tenant, mint in dashboard) — see auth.md.
  • OAuth 2.1 access token (multi-tenant, on behalf of a Scripe user) — see oauth.md.
Both use the identical wire format and identical scope vocabulary; the difference is who issues the token and how it rotates. Quick reminders:
  • One key per workspace. There is no organisation-wide super key.
  • Live and test keys hit the same endpoints; test keys are flagged in the audit log and skip side-effects from Phase 4 onwards.
  • Keys are HMAC-SHA-256 hashed at rest. We never store the plaintext.
  • Revocation is synchronous at the edge (≤ 5 s worst-case TTL).

​
Versioning

Pin a date-stamped version on every request: 
Scripe-Api-Version: 2026-08-01
If you omit the header we default to the current version, which can move under your feet. Pin in production. See conventions.md for the deprecation policy.

​
Endpoint catalogue (v1.0)

MethodPathScopeNotes
GET/healthnoneLiveness probe; unauthenticated.
GET/health/authany valid keyAuthenticated probe — useful for canary checks.
GET/workspaces/meany valid keyResolves the authenticated workspace + principal.
GET/projectsany valid keyPaginated list of projects.
GET/projects/{projectId}any valid keySingle project read.
GET/notesnotes:readList notes for a project; supports date / cursor.
GET/notes/{noteId}notes:readSingle note read.
POST/notesnotes:writeCreate a note + queue slot. Idempotent.
GET/postsposts:readList posts for a project; supports status CSV.
GET/posts/{postId}posts:readSingle post read.
POST/postsposts:writeCreate a draft (or scheduled) post. Idempotent.
GET/sources/{sourceId}notes:readSingle source/transcription read (preview-only).
POST/sourcessources:writeCreate a source. type: "text" returns a Source; type: "file" enqueues a job. Idempotent.
POST/posts/generationsposts:writeAsync post generation from text or note. Idempotent.
POST/uploadssources:write or knowledge:writeMint a presigned S3 PUT URL for type: "file" ingest.
POST/knowledgeknowledge:writeAsync ingest of text/file/url/youtube into the Knowledge Base. Idempotent.
GET/jobsany valid keyList async jobs (paginated).
GET/jobs/{jobId}any valid keySingle job read with progress snapshot.
POST/jobs/{jobId}/cancelany valid keyCancel a QUEUED job.
The OpenAPI 3.1 spec lives at packages/api-public/openapi/v1.yaml in the repo. Use it to generate clients (we recommend openapi-generator or @hey-api/openapi-ts).

​
Conventions

The same rules apply to every endpoint:
  • Pagination — opaque cursor-based, never page numbers. Loop until pagination.has_more is false.
  • Errors — uniform envelope with stable code identifiers; see errors/ for one page per code.
  • Rate limits — workspace-scoped, sliding 60-second window. Read endpoints share a 120 req/min bucket; the response carries X-RateLimit-* and Retry-After on 429.
  • Resource IDs — every resource exposes a typed prefix (note_, post_, proj_, src_).
  • Idempotency — pass Idempotency-Key on every write request. The server replays the original response for 24h.

​
Need help?