Skip to main content

​
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.

​
Reading documents

  • 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.

​
POST /v1/knowledge

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. 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.
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.