# Scripe

> Scripe developer docs — REST API, authentication, conventions, and error reference.

## Docs

- [Analytics overview (current vs previous period)](https://apidocs.scripe.io/api-reference/analytics/analytics-overview-current-vs-previous-period.md): Aggregate analytics for one or more projects over a date range: post count, impressions, engagement rate, follower growth, and posting activity — each compared against the immediately preceding period of equal length.
- [Per-post analytics (library)](https://apidocs.scripe.io/api-reference/analytics/per-post-analytics-library.md): Offset-paginated per-post LinkedIn metrics (views, likes, comments, shares, engagement rate) for one or more projects, newest first.
- [Search viral posts (inspiration)](https://apidocs.scripe.io/api-reference/analytics/search-viral-posts-inspiration.md): Semantic search over the inspiration feed for high-performing LinkedIn posts relevant to a topic. Returns posts from other authors (the project's own posts are excluded) with engagement metrics.
- [Authenticated key smoke test](https://apidocs.scripe.io/api-reference/health/authenticated-key-smoke-test.md): Returns the resolved workspace + principal so customers can wire up smoke tests for their API key. Counts against the read-bucket rate limit.
- [Public health probe](https://apidocs.scripe.io/api-reference/health/public-health-probe.md): Reports the status of the API + its critical dependencies (DB, Redis, audit buffer). Returns `200` when all OK, `503` with `status: degraded` when any dependency is unhealthy.
- [Cancel a `QUEUED` job](https://apidocs.scripe.io/api-reference/jobs/cancel-a-`queued`-job.md): Transitions a `QUEUED` job to `CANCELLED`. Returns the updated job envelope. Cancelling any other status returns `409 not_cancellable` — workers do not poll for cancellation mid-run in v1.
- [Get a single job (with progress snapshot)](https://apidocs.scripe.io/api-reference/jobs/get-a-single-job-with-progress-snapshot.md): Returns the job row plus the latest progress snapshot pulled from Redis. Customers polling for completion should call this endpoint and inspect `data.status` and `data.progress`.
- [List async jobs in the workspace](https://apidocs.scripe.io/api-reference/jobs/list-async-jobs-in-the-workspace.md): Cursor-paginated listing of every async job submitted by the workspace. Filter by `type`, `status`, and date range.
- [Index a knowledge-base document asynchronously](https://apidocs.scripe.io/api-reference/knowledge/index-a-knowledge-base-document-asynchronously.md): Kick off an async ingest into the workspace's knowledge base. Four input shapes are accepted (`type: text|file|url|youtube`). Returns a `Job` envelope; poll `GET /v1/jobs/{jobId}` until the status transitions to `DONE` and `result.documentId` becomes available.
- [Create a note + paired calendar slot](https://apidocs.scripe.io/api-reference/notes/create-a-note-+-paired-calendar-slot.md): Creates a note and the paired `tQueueSlot` row that drives the calendar UI. The slot's `date` defaults to "now" if `date` is omitted. Honours `Idempotency-Key` for 24h dedup — see `/docs/api/v1/idempotency`.
- [Get a single note](https://apidocs.scripe.io/api-reference/notes/get-a-single-note.md): Returns the note plus its paired calendar slot.
- [List notes for a project](https://apidocs.scripe.io/api-reference/notes/list-notes-for-a-project.md): Cursor-paginated list of notes scoped to a project. Filter by folder (`null` for inbox), date range (paired-slot date), and custom limit. Sorted by `(createdAt DESC, id DESC)`.
- [Create a draft (or scheduled) post](https://apidocs.scripe.io/api-reference/posts/create-a-draft-or-scheduled-post.md): Creates a `tPost` row in `draft` status (or `scheduled` if `scheduledFor` is set). Always pairs the post with an empty `tTranscription` placeholder for parity with the dashboard.
- [Generate a LinkedIn post asynchronously](https://apidocs.scripe.io/api-reference/posts/generate-a-linkedin-post-asynchronously.md): Kick off an AI-driven post generation. The handler validates input, reserves AI-spend capacity, enqueues an async job, and returns a `Job` envelope. The customer polls `GET /v1/jobs/{jobId}` until status transitions to `DONE` or `FAILED`.
- [Get a single post](https://apidocs.scripe.io/api-reference/posts/get-a-single-post.md): Resolve a `post_*` id to the post shape.
- [List posts for a project](https://apidocs.scripe.io/api-reference/posts/list-posts-for-a-project.md): Cursor-paginated list of posts scoped to a project. Filter by comma-separated `status`, date range (`createdAt`), and custom limit.
- [List the workspace's custom post statuses](https://apidocs.scripe.io/api-reference/posts/list-the-workspaces-custom-post-statuses.md): Returns the workspace's custom statuses (the kanban columns). Use a returned `id` as the `statusId` when calling `PATCH /posts/{postId}`, or use its `category` with `statusCategory`.
- [Update a post (content, status, schedule)](https://apidocs.scripe.io/api-reference/posts/update-a-post-content-status-schedule.md): Partial update of a post. Any subset of `content`, `title`, `contentType` may be sent. Status can be changed via either `statusCategory` (move to the workspace's default status in that lifecycle category) or an explicit `statusId` (from `GET /post-statuses`) — the two are mutually exclusive.
- [Get a single project](https://apidocs.scripe.io/api-reference/projects/get-a-single-project.md): Resolve a `proj_*` id to the project shape.
- [List projects in the workspace](https://apidocs.scripe.io/api-reference/projects/list-projects-in-the-workspace.md): Cursor-paginated list of every project owned by your workspace. Sorted by `(createdAt DESC, id DESC)`.
- [Create a transcription (Source) from text or upload](https://apidocs.scripe.io/api-reference/sources/create-a-transcription-source-from-text-or-upload.md): Two body shapes:
- [Get a single transcription source](https://apidocs.scripe.io/api-reference/sources/get-a-single-transcription-source.md): Returns the source row plus a 2000-character text preview. The full transcript is intentionally never exposed via the public API. S3 storage keys are stripped from the response.
- [Mint a presigned S3 PUT URL](https://apidocs.scripe.io/api-reference/uploads/mint-a-presigned-s3-put-url.md): Returns a single-use presigned PUT URL the customer uploads bytes to directly. The returned `id` is an opaque handle (`upl_...`) the customer then references via `POST /v1/sources` (`type: "file"`) or `POST /v1/knowledge` (`type: "file"`) to kick off ingestion.
- [Create webhook endpoint](https://apidocs.scripe.io/api-reference/webhooks/create-webhook-endpoint.md): Register a new outbound webhook endpoint. The response includes the plaintext signing secret — store it immediately, the API will never return it again. Subsequent reads expose only `secretLast4`.
- [Delete webhook endpoint](https://apidocs.scripe.io/api-reference/webhooks/delete-webhook-endpoint.md): Permanently remove an endpoint. In-flight deliveries continue until they terminate (`DELIVERED` or `FAILED_PERMANENT`); new events stop fanning out immediately. Idempotent — repeated deletes return the same shape.
- [Get webhook endpoint](https://apidocs.scripe.io/api-reference/webhooks/get-webhook-endpoint.md): Fetch a single endpoint by id. The plaintext signing secret is never returned — only `secretLast4`. `404` is returned for ids in other workspaces, by design.
- [List webhook endpoints](https://apidocs.scripe.io/api-reference/webhooks/list-webhook-endpoints.md): Returns every webhook endpoint registered for the workspace, ordered by `createdAt` descending. The plaintext signing secret is never returned by this endpoint — only `secretLast4`. Use `POST /v1/webhook-endpoints/{endpointId}/rotate-secret` if the plaintext is lost.
- [Rotate the endpoint's signing secret](https://apidocs.scripe.io/api-reference/webhooks/rotate-the-endpoints-signing-secret.md): Mint a new plaintext signing secret and persist it as the canonical secret for the endpoint. The response carries the plaintext once; future reads expose only `secretLast4`.
- [Update webhook endpoint](https://apidocs.scripe.io/api-reference/webhooks/update-webhook-endpoint.md): Patch any subset of name, URL, events, isActive, projectId. Anything not present is left unchanged. Changing the URL re-pins the resolved IP (and re-runs the SSRF check). Setting `isActive: true` on an auto-disabled endpoint clears `disabledReason`.
- [Resolved workspace + principal](https://apidocs.scripe.io/api-reference/workspace/resolved-workspace-+-principal.md): Returns the workspace your API key is scoped to plus the principal (the API key's id and granted scopes). The `workspace.id` field is the Clerk organisation id (`org_*`).
- [Auth](https://apidocs.scripe.io/api/v1/auth.md)
- [Conventions](https://apidocs.scripe.io/api/v1/conventions.md)
- [Bad cursor](https://apidocs.scripe.io/api/v1/errors/bad_cursor.md)
- [Bad pagination](https://apidocs.scripe.io/api/v1/errors/bad_pagination.md)
- [Idempotency key conflict](https://apidocs.scripe.io/api/v1/errors/idempotency_key_conflict.md)
- [Errors](https://apidocs.scripe.io/api/v1/errors/index.md)
- [Internal error](https://apidocs.scripe.io/api/v1/errors/internal_error.md)
- [Invalid request](https://apidocs.scripe.io/api/v1/errors/invalid_request.md)
- [Invalid token](https://apidocs.scripe.io/api/v1/errors/invalid_token.md)
- [Key expired](https://apidocs.scripe.io/api/v1/errors/key_expired.md)
- [Key revoked](https://apidocs.scripe.io/api/v1/errors/key_revoked.md)
- [Method not allowed](https://apidocs.scripe.io/api/v1/errors/method_not_allowed.md)
- [Not cancellable](https://apidocs.scripe.io/api/v1/errors/not_cancellable.md)
- [Not found](https://apidocs.scripe.io/api/v1/errors/not_found.md)
- [Payload too large](https://apidocs.scripe.io/api/v1/errors/payload_too_large.md)
- [Plan not eligible](https://apidocs.scripe.io/api/v1/errors/plan_not_eligible.md)
- [Rate limited](https://apidocs.scripe.io/api/v1/errors/rate_limited.md)
- [Scope missing](https://apidocs.scripe.io/api/v1/errors/scope_missing.md)
- [Service unavailable](https://apidocs.scripe.io/api/v1/errors/service_unavailable.md)
- [Spend cap exceeded](https://apidocs.scripe.io/api/v1/errors/spend_cap_exceeded.md)
- [Unauthenticated](https://apidocs.scripe.io/api/v1/errors/unauthenticated.md)
- [Unprocessable](https://apidocs.scripe.io/api/v1/errors/unprocessable.md)
- [Version unsupported](https://apidocs.scripe.io/api/v1/errors/version_unsupported.md)
- [Workspace mismatch](https://apidocs.scripe.io/api/v1/errors/workspace_mismatch.md)
- [Health](https://apidocs.scripe.io/api/v1/health.md)
- [Idempotency](https://apidocs.scripe.io/api/v1/idempotency.md)
- [V1](https://apidocs.scripe.io/api/v1/index.md)
- [Jobs](https://apidocs.scripe.io/api/v1/jobs.md)
- [Notes](https://apidocs.scripe.io/api/v1/notes.md)
- [Posts](https://apidocs.scripe.io/api/v1/posts.md)
- [Projects](https://apidocs.scripe.io/api/v1/projects.md)
- [Sources](https://apidocs.scripe.io/api/v1/sources.md)
- [Workspaces](https://apidocs.scripe.io/api/v1/workspaces.md)

## OpenAPI Specs

- [v1](https://apidocs.scripe.io/openapi/v1.yaml)
- [openapi](https://apidocs.scripe.io/api-reference/openapi.json)

## Optional

- [Support](mailto:support@scripe.io)
- [Status](https://status.scripe.io)