---
title: "Create a knowledge base"
method: POST
path: "/v1/knowledge-base"
tags: ["Knowledge Base"]
---

# Create a knowledge base

`POST /v1/knowledge-base`

Creates a knowledge base. TEXT and JSON sources accept inline `content`. FILE sources require `filename`, `mimeType`, and base64-encoded `contentBase64` — the file is decoded server-side, stored in S3, and (for PDFs) text-extracted inline before the response returns.

## Request body

- object — Input for creating a knowledge base. See `sourceType` for which fields are required.
  - `name` string, required — Customer-facing name. Unique within the project. Required.
  - `description` string, nullable — Optional short blurb shown in pickers.
  - `sourceType` 'TEXT' | 'FILE' | 'JSON', required — Source types accepted via the public create endpoint. URL ingestion is currently only available in the platform UI.
  - `content` string, nullable — For TEXT: raw markdown/text. For JSON: a JSON string (validated server-side and re-formatted with stable whitespace). Required for TEXT and JSON; omit for FILE.
  - `filename` string, nullable — For FILE: customer-supplied filename (informational only — used for download links).
  - `mimeType` 'application/pdf' | 'text/plain' | 'text/markdown', nullable — For FILE: mime type of the uploaded file. Only `application/pdf`, `text/plain`, and `text/markdown` are accepted.
  - `contentBase64` string, nullable — For FILE: base64-encoded file bytes. Required for FILE. Max 10 MB after decoding. PDFs are text-extracted server-side; image-only PDFs are rejected.

## Response `201`

The created knowledge base.

- object
  - `data` object, required — A customer-uploaded reference document attached to custom metrics as ground truth at evaluation time.
    - `id` string, uuid, required — Unique identifier of the knowledge base.
    - `name` string, required — Customer-supplied name. Unique within the project.
    - `description` string, nullable, required — Optional customer-supplied description.
    - `sourceType` 'TEXT' | 'FILE' | 'JSON' | 'URL', required — How the knowledge base content was provided. TEXT/JSON are stored as-is; FILE was uploaded and its text content extracted (PDF → text); URL was scraped from a webpage into markdown.
    - `status` 'READY' | 'PROCESSING' | 'PENDING_UPLOAD' | 'FAILED', required — Lifecycle of the knowledge base. READY means the content is available to metrics. PROCESSING is set during PDF text extraction. FAILED means extraction errored — see `errorMessage`.
    - `originalFilename` string, nullable, required — For FILE source: the customer-supplied filename. Null for TEXT/JSON/URL.
    - `mimeType` string, nullable, required — For FILE source: the mime type of the uploaded file. Null for TEXT/JSON/URL.
    - `sourceUrl` string, nullable, required — For URL source: the page that was scraped into markdown. Null for TEXT/JSON/FILE.
    - `byteSize` integer, required — Size of the content the model will read at evaluation time. For FILE this is the EXTRACTED text size, not the original PDF size.
    - `contentHash` string, nullable, required — SHA-256 of the content. Stable across whitespace-equivalent edits for JSON (pretty-printed before hashing). Use it to detect change without diffing the content.
    - `errorMessage` string, nullable, required — When `status` is FAILED, the reason. Null otherwise.
    - `createdAt` string, required — Creation timestamp in ISO 8601 format.
    - `updatedAt` string, required — Last update timestamp in ISO 8601 format.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `500` — Internal Server Error

## Changes

- **2026-08-17** `887b091b3d81` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/roarkhq/apis/roark-analytics-api/changes/v1/knowledge-base/post.md)

---

[API](https://skmtc.dev/roarkhq/apis/roark-analytics-api.md) · [All operations](https://skmtc.dev/roarkhq/apis/roark-analytics-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/roarkhq/roark-analytics-api/revisions/1d61b68e9429/schema)