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)

Method	Path	Scope	Notes
GET	`/health`	none	Liveness probe; unauthenticated.
GET	`/health/auth`	any valid key	Authenticated probe — useful for canary checks.
GET	`/workspaces/me`	any valid key	Resolves the authenticated workspace + principal.
GET	`/projects`	any valid key	Paginated list of projects.
GET	`/projects/{projectId}`	any valid key	Single project read.
GET	`/notes`	`notes:read`	List notes for a project; supports date / cursor.
GET	`/notes/{noteId}`	`notes:read`	Single note read.
POST	`/notes`	`notes:write`	Create a note + queue slot. Idempotent.
GET	`/posts`	`posts:read`	List posts for a project; supports `status` CSV.
GET	`/posts/{postId}`	`posts:read`	Single post read.
POST	`/posts`	`posts:write`	Create a draft (or scheduled) post. Idempotent.
GET	`/sources/{sourceId}`	`notes:read`	Single source/transcription read (preview-only).
POST	`/sources`	`sources:write`	Create a source. `type: "text"` returns a `Source`; `type: "file"` enqueues a job. Idempotent.
POST	`/posts/generations`	`posts:write`	Async post generation from text or note. Idempotent.
POST	`/uploads`	`sources:write` or `knowledge:write`	Mint a presigned S3 PUT URL for `type: "file"` ingest.
POST	`/knowledge`	`knowledge:write`	Async ingest of `text`/`file`/`url`/`youtube` into the Knowledge Base. Idempotent.
GET	`/jobs`	any valid key	List async jobs (paginated).
GET	`/jobs/{jobId}`	any valid key	Single job read with progress snapshot.
POST	`/jobs/{jobId}/cancel`	any valid key	Cancel 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?

Email [email protected] for integration questions.
Email [email protected] for suspected leaks. We respond within one business day.
Status page: status.scripe.io (Phase 5 will surface API-specific health alongside the dashboard).

Getting started

Resources

Errors

V1

Scripe API v1

TL;DR

Base URL

Authentication

Versioning

Endpoint catalogue (v1.0)

Conventions

Need help?

​Scripe API v1

​TL;DR

​Base URL

​Authentication

​Versioning

​Endpoint catalogue (v1.0)

​Conventions

​Need help?

Scripe API v1

TL;DR

Base URL

Authentication

Versioning

Endpoint catalogue (v1.0)

Conventions

Need help?