Skip to main content
POST
Create or upsert a knowledge source

Authorizations

Authorization
string
header
required

Your secret key (pep_sk_…) from Settings → API. Keys are org-scoped; treat them like passwords.

Headers

Idempotency-Key
string

Body

application/json
kind
enum<string>
required
Available options:
text,
url,
file,
website
title
string

Required for text; optional for url/website (defaults to the host, upgraded by the page title) and file (defaults to the filename).

body
string

Required for text. Max 500,000 characters.

url
string

Required for url (the page) and website (the site root). http(s) only.

max_pages
integer
default:30

website kind: page cap per refresh.

Required range: 1 <= x <= 50
filename
string

file kind: the original filename (extension decides the extractor: txt, md, pdf, docx).

data
string

file kind: strict base64 of the file, max 10MB decoded.

external_id
string

Your sync key — unique per organization; makes POST an upsert.

Maximum string length: 255
language
string

Two-letter hint; detection at refresh may override.

metadata
object

Up to 20 string values (≤500 chars each). Returned verbatim, never interpreted.

agents
string[]

Agent slugs this source is active for — declarative: the activation set becomes exactly this list. Omit to leave activations untouched.

Response

Upserted an existing source (includes body for single-entry kinds).

object
string
required
Allowed value: "knowledge_source"
id
integer
required
kind
enum<string>
required
Available options:
text,
url,
file,
website
title
string
required
status
enum<string>
required

Aggregated from the source's entries: ready (everything ingested), updating (work in flight — poll), attention (usable with some failed entries), failed (nothing usable).

Available options:
ready,
updating,
attention,
failed
agents
string[]
required

Slugs of the agents this source is active for.

metadata
object
required
entries
object
required

Entry counts by status (one entry per page for websites).

archived
boolean
required
created_at
string<date-time>
required
external_id
string | null
url
string | null

The page (url) or site root (website).

failure_reason
string | null

Single-entry kinds: why processing failed, human-readable. Websites report per-entry reasons under /entries.

language
string | null
digest
string | null

What the agent understood from this source (generated after each refresh).

max_pages
integer | null

website kind only.

last_update_at
string<date-time> | null

When the last refresh run landed — the freshness stamp.

body
string

Full text. Present on retrieve/create/update for text/url/file; websites read per-page content via /entries.