Create a knowledge base

A knowledge base grounds a target's evaluations in your own content, so Spectral tests against what your system is supposed to know.

We support three strategies to create a knowledge base:

File upload: You upload documents directly (PDF, DOCX, Markdown, and similar)
Crawl: Spectral starts at a URL and follows links to ingest a whole site, up to a page limit
URL list: You provide a fixed list of URLs to ingest

You create a knowledge base with a single call scoped to a target, then wait for Spectral to ingest the content.

Send the request

Send a POST to the sub-path for your chosen strategy. Crawl and URL list take a JSON body; file upload uses multipart/form-data.

Send the documents as multipart/form-data files fields (repeat files for each document), passing language - the language of the content (defaults to English) - as a query parameter.

curl -X POST "https://spectral.principled.app/api/v1/targets/9f8c2.../knowledge-bases/file-upload?language=English" \
     -H "Authorization: Bearer ak_****" \
     -F 'files=@returns-policy.pdf' \
     -F 'files=@delivery-faq.md'

warning

The total upload may not exceed 30 MB across all files.

Read the response

A 201 returns the new knowledge base together with the job that builds it:

{
  "knowledge_base": {
    "id": "3b1f7...",
    "kind": "file_upload",
    "language": "English",
    "status": "queued",
    "created_at": "2026-06-19T12:00:00Z"
  },
  "job": {
    "id": "job_8f2a1...",
    "status": "queued",
    "kind": "populate_knowledge_base",
    "resource": {
      "type": "knowledge_base",
      "id": "3b1f7..."
    },
    "created_at": "2026-06-19T12:00:00Z"
  }
}

The knowledge base exists, but its status is queued: ingestion runs in the background and the knowledge base is not ready to use yet. Keep the job.id.

Wait for the job to finish

Ingestion is asynchronous. Poll the job with GET /api/v1/jobs/{job_id} until its status is terminal:

curl https://spectral.principled.app/api/v1/jobs/job_8f2a1... \
     -H "Authorization: Bearer ak_****"

{
  "id": "job_8f2a1...",
  "status": "succeeded",
  "kind": "populate_knowledge_base",
  "resource": {
    "type": "knowledge_base",
    "id": "3b1f7..."
  },
  "created_at": "2026-06-19T12:00:00Z",
  "started_at": "2026-06-19T12:00:03Z",
  "ended_at": "2026-06-19T12:02:18Z"
}

A status of succeeded means the knowledge base is populated and ready to use in evaluations. A status of failed means ingestion did not complete.

tip

Polling is a common pattern across Spectral's asynchronous endpoints. See Async jobs for the full polling pattern.