Skip to main content
PATCH
Update a knowledge source

Authorizations

Authorization
string
header
required

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

Path Parameters

id
integer
required

Body

application/json
title
string
body
string

text sources only.

reading_brief
string | null

Reading guidance for the whole source; replaces the source's own ingestion instructions with this one text (null clears them). A change re-reads every page from its cached text (no re-crawl). Prefer /ingestion_instructions for several asks or asks on pages and facts.

refresh_every
enum<string> | null

Scheduled-refresh cadence; null returns the source to manual refresh.

Available options:
daily,
weekly,
monthly,
null
max_pages
integer

website sources only.

Required range: 1 <= x <= 50
language
string
visibility
enum<string>

public: visitors see the source named under the replies it backs; private: never cited. Past replies keep what visitors saw.

Available options:
public,
private
public_title
string | null

The name visitors see; required when making a source public against the default rule. null clears it (title is used).

metadata
object
agents
string[]

Response

The updated 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
visibility
enum<string>
required

public: visitors see the source named under the replies it backs (pill, quotes, link). private: never cited to visitors; its facts still inform replies.

Available options:
public,
private
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). queued counts the pending pages still waiting for a platform reading slot.

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

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

public_title
string | null

The name visitors see when the source is public (falls back to title).

failure_reason
string | null

Why the source is not usable, human-readable: the first failed entry's reason, or — when the run itself was refused (no credits, a crawl error) — the latest run's. Websites also report per-entry reasons under /entries.

language
string | null

Two-letter code: the language this source's facts and summary are written in.

digest
string | null

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

reading_brief
string | null

Reading guidance for the whole source: what the agent should specifically look for on every page. Derived from the live ingestion instructions targeting the source (newline-joined). Steers extraction only — facts still require a verbatim excerpt from the page.

refresh_every
enum<string> | null

Scheduled-refresh cadence; null = manual only. url/website kinds only.

Available options:
daily,
weekly,
monthly,
null
next_refresh_at
string<date-time> | null

When the scheduler owes the next refresh (any refresh resets the clock). null when manual.

reading
object | null

The reading queue, present while pages of this source wait to be fetched. Pages are read a few at a time platform-wide; ahead is how many pages of other sites are read before this source's first waiting page, eta_seconds a rough wait. null once nothing waits.

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.