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

# Knowledge

# 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](./auth.md#12-scopes)). 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 theme={null}
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.**

***

## `POST /v1/knowledge`

Always **asynchronous** — even text is chunked and embedded by a
worker. Every input shape returns a [`Job` envelope](./jobs.md); 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`](./uploads.md)) | 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 theme={null}
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](./jobs.md#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](./mcp-tools.md#4-inline-file-content-content_base64)
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`](./mcp-tools.md#2-write-tools)): 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`](./errors/admin_required.md). One case refuses:
a document that is **one page of a dashboard sync** (a website crawl,
a Notion connection, or any [synced source](./synced-sources.md))
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](./mcp-tools.md#211-removing-knowledge-delete_knowledge_doc).

***

## 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](./synced-sources.md), a profile's own post history
  included) — dashboard-only.
* **Updating documents** — re-ingest creates a new document.