Create or upsert a knowledge source
One source per ORIGIN: a paste (text), a document (file), a single page (url), or a whole site (website — pages are kept as entries beneath one source). With external_id, this endpoint UPSERTS: 201 when a new source is created, 200 when the existing source with that external_id was updated (and refreshed if its content changed — an identical payload short-circuits without re-processing, so retries are free). Supply Idempotency-Key for byte-exact retry semantics on creates without external_id. Website sources are limited to 5 creations per hour per key.
Authorizations
Your secret key (pep_sk_…) from Settings → API. Keys are org-scoped; treat them like passwords.
Headers
Body
text, url, file, website Required for text; optional for url/website (defaults to the host, upgraded by the page title) and file (defaults to the filename).
Required for text. Max 500,000 characters.
Required for url (the page) and website (the site root). http(s) only.
website kind: page cap per refresh.
1 <= x <= 50file kind: the original filename (extension decides the extractor: txt, md, pdf, docx).
file kind: strict base64 of the file, max 10MB decoded.
Your sync key — unique per organization; makes POST an upsert.
255Two-letter hint; detection at refresh may override.
Up to 20 string values (≤500 chars each). Returned verbatim, never interpreted.
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).
"knowledge_source"text, url, file, website Aggregated from the source's entries: ready (everything ingested), updating (work in flight — poll), attention (usable with some failed entries), failed (nothing usable).
ready, updating, attention, failed Slugs of the agents this source is active for.
Entry counts by status (one entry per page for websites).
The page (url) or site root (website).
Single-entry kinds: why processing failed, human-readable. Websites report per-entry reasons under /entries.
What the agent understood from this source (generated after each refresh).
website kind only.
When the last refresh run landed — the freshness stamp.
Full text. Present on retrieve/create/update for text/url/file; websites read per-page content via /entries.

