> ## 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. # V1 # 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](./conventions.md#versioning) — > 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](./mcp.md). For multi-tenant integrations that need OAuth on behalf of a Scripe user, see [oauth.md](./oauth.md). The semantics under the hood are identical across REST + MCP. *** ## TL;DR ```bash theme={null} # 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](./mcp.md). *** ## Authentication ```http theme={null} 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](./auth.md). * **OAuth 2.1 access token** (multi-tenant, on behalf of a Scripe user) — see [oauth.md](./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: ```http theme={null} 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](./conventions.md#versioning) 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`](../../../packages/api-public/openapi/v1.yaml) in the repo. Use it to generate clients (we recommend [`openapi-generator`](https://openapi-generator.tech/) or [`@hey-api/openapi-ts`](https://heyapi.dev/)). *** ## Conventions The same rules apply to every endpoint: * [Pagination](./conventions.md#pagination) — opaque cursor-based, never page numbers. Loop until `pagination.has_more` is `false`. * [Errors](./conventions.md#errors) — uniform envelope with stable `code` identifiers; see [errors/](./errors/) for one page per code. * [Rate limits](./conventions.md#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](./conventions.md#resource-ids) — every resource exposes a typed prefix (`note_`, `post_`, `proj_`, `src_`). * [Idempotency](./idempotency.md) — pass `Idempotency-Key` on every write request. The server replays the original response for 24h. *** ## Need help? * Email **[support@scripe.io](mailto:support@scripe.io)** for integration questions. * Email **[security@scripe.io](mailto:security@scripe.io)** for suspected leaks. We respond within one business day. * Status page: [status.scripe.io](https://status.scripe.io) (Phase 5 will surface API-specific health alongside the dashboard).