> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yalg.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Knowledge Base

> Create, upload, search, and manage workspace knowledge used by YALG generation workflows.

Knowledge Base sources are private, workspace-scoped inputs that YALG can retrieve when generating posts, scripts, carousels, shorts, blogs, and ads.

Send `x-workspace-id` when an API key has access to several workspaces. Without it, YALG uses the owner's default workspace.

## Create a note

```bash theme={null}
curl https://api.yalg.ai/v1/knowledge-sources \
  -H "x-api-key: $YALG_API_KEY" \
  -H "x-workspace-id: $YALG_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "How we improved activation",
    "content": "We removed two onboarding steps and activation increased.",
    "category": "insight",
    "tags": ["product", "activation"],
    "contentScopes": ["linkedin_post", "blog_article"],
    "priority": 2
  }'
```

## Upload voice or import a spreadsheet

* `POST /v1/knowledge-sources/audio` accepts multipart form data with an `audio` file.
* `POST /v1/knowledge-sources/imports/spreadsheet` accepts an XLSX or XLS file in the `file` field.

These operations process each resulting source asynchronously.

## Upload PDF, PPTX, or TXT files

File uploads use direct, private upload sessions:

1. Compute the file's SHA-256 digest.
2. Call `POST /v1/knowledge-sources/upload-sessions` with one to 20 file descriptors.
3. Upload every file with `PUT` to its returned `uploadUrl`, including the returned `requiredHeaders`.
4. Call `POST /v1/knowledge-sources/upload-sessions/{sessionId}/finalize` with each `sourceId` and digest.

Each file becomes one source. A file is limited to 50 MB and a workspace to 1 GB of Knowledge Base assets.

## List and inspect sources

```http theme={null}
GET /v1/knowledge-sources?query=activation&status=ready&page=1&pageSize=20
GET /v1/knowledge-sources/{id}
GET /v1/knowledge-sources/{id}/download
```

The detail response can include extracted chunks and page or slide positions. Downloads are private and require authentication.

## Generate with pinned or excluded sources

Normal generation endpoints accept `pinnedSourceIds` and `excludedSourceIds`. A pinned source is guaranteed to participate in retrieval; an excluded source cannot participate.

```json theme={null}
{
  "brief": "Explain the activation change to product leaders",
  "pinnedSourceIds": ["123e4567-e89b-12d3-a456-426614174000"],
  "excludedSourceIds": []
}
```

Retrieval provenance is returned separately as `knowledgeTrace` and is never inserted automatically into published content.

## Reindex or delete

* `POST /v1/knowledge-sources/{id}/reindex` creates a fresh index revision.
* `DELETE /v1/knowledge-sources/{id}` immediately hides the source and starts asynchronous private-file and vector cleanup.

<Note>
  Direct IDs, searches, downloads, generation pins, and deletes are always
  restricted to the active workspace.
</Note>