Knowledge Base - YALG Developer Docs

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

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:

Compute the file’s SHA-256 digest.
Call POST /v1/knowledge-sources/upload-sessions with one to 20 file descriptors.
Upload every file with PUT to its returned uploadUrl, including the returned requiredHeaders.
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

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.

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

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

​Create a note

​Upload voice or import a spreadsheet

​Upload PDF, PPTX, or TXT files

​List and inspect sources

​Generate with pinned or excluded sources

​Reindex or delete

Create a note

Upload voice or import a spreadsheet

Upload PDF, PPTX, or TXT files

List and inspect sources

Generate with pinned or excluded sources

Reindex or delete