API v1 · Resources

Knowledge

The Knowledge Base grounds Scripe's AI output (post generation, hook ideation) in your own material. Ingest text, files, web pages, or YouTube videos; Scripe chunks, embeds, and indexes them.

Scopes: knowledge:read / knowledge:write — grantable to API keys and OAuth tokens alike (see auth.md §1.2). Full schemas: OpenAPI reference → Knowledge.

Method	Path	Notes
GET	`/v1/knowledge`	Paginated document list visible to a project.
GET	`/v1/knowledge/{documentId}`	One document: metadata, status, tags, chunk count, preview.
POST	`/v1/knowledge`	Async ingest — always returns a `Job`.

Reading documents

bash

curl -s "https://api.scripe.io/v1/knowledge?projectId=proj_01J9ZA…" \
  -H "Authorization: Bearer scripe_oat_…" \
  -H "Scripe-Api-Version: 2026-08-10"

The list shows the documents visible to that project: project-bound documents plus workspace-wide ones (which honour the dashboard's assignment visibility — no assignments means visible to every project). Ephemeral chat uploads never appear.
A single read returns metadata, status, tags, chunk count, and a 2,000-character text preview. The full document body is never returned over the API.

Always asynchronous — even text is chunked and embedded by a worker. Every input shape returns a Job envelope; poll GET /v1/jobs/{jobId} until status: "DONE", then result.documentId names the new kb_* document.

`type`	Job type	Inputs	Notes
`text`	`KB_INGEST_TEXT`	`name`, `text` (≤ 1 MB)	Usually completes in seconds.
`file`	`KB_INGEST_FILE`	`name`, `uploadId` (from `/v1/uploads`)	Audio/video transcribed; documents text-extracted.
`url`	`KB_INGEST_URL`	`url` (http/https), optional `name`	Fetched + extracted. No subpage recursion.
`youtube`	`KB_INGEST_YOUTUBE`	`url` (YouTube domain), optional `name`	Transcript pulled when available; falls back to audio transcription.

All shapes accept an optional projectId:

omitted / null → the document is workspace-scoped (visible per assignment rules);
present → bound to that single project. A foreign projectId (or an uploadId minted in another workspace) returns 404 not_found.

bash

curl -i https://api.scripe.io/v1/knowledge \
  -X POST \
  -H "Authorization: Bearer scripe_oat_…" \
  -H "Scripe-Api-Version: 2026-08-10" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "type": "url",
    "url": "https://example.com/2026-pricing-rationale"
  }'

Ingest is metered by the AI budget — a submit that would exceed it fails with 402 before enqueueing anything.

MCP hosts can skip the two-step upload for small files: the add_to_knowledge_base tool takes bytes inline as base64 up to ~3 MB decoded; anything larger has to come through this flow. On MCP, note the projectId nuance: omitting it uses the grant's default project, while an explicit projectId: null scopes workspace-wide.

Deleting documents

Knowledge deletion is MCP-only and two-phase (delete_knowledge_doc): the first call returns a proposal naming everything the delete removes — the document, every chunk and embedding, the visibility assignments, any stored file — and only a replay with the confirmation token executes, transactionally.

It requires the knowledge:destroy scope (never implied by knowledge:write or any alias). Workspace-wide documents additionally require admin authority in the workspace the document is shared with — not always your own, see admin_required. One case refuses: a document that is one page of a dashboard sync (a website crawl, a Notion connection, or any synced source) answers conflict naming the sync — deleting one page is pointless because the next sync run restores it. Sync membership is what the document's folder says, not its type: a one-off URL ingested with type: "url" has no folder, no sync behind it, and deletes normally. See MCP tools §2.11.

What's NOT here (yet)

REST delete — see above.
Full document text — previews and chunk counts only.
Synced-source ingest (a website crawl, a Notion connection, or any synced source, a profile's own post history included) — dashboard-only.
Updating documents — re-ingest creates a new document.

Reading documents

POST /v1/knowledge

Deleting documents

What's NOT here (yet)

`POST /v1/knowledge`