> ## Documentation Index > Fetch the complete documentation index at: https://docs.pepline.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml https://app.pepline.ai/api/v1/openapi.yaml post /knowledge_sources openapi: 3.1.0 info: title: pepline API version: '1' description: | The pepline knowledge ingestion API: push knowledge into your organization's library from your own systems — CMS hooks, sync scripts, Zapier/Make/n8n scenarios — and keep whole websites fresh. One inbound API instead of N connectors; you own the trigger, we own idempotency. servers: - url: https://app.pepline.ai/api/v1 security: - bearerAuth: [] tags: - name: Organization description: The identity behind your key — confirm it works and read your agent slugs. - name: Knowledge sources description: >- Push and sync the knowledge your agents stand on — text, files, pages, whole websites. - name: Agents description: List and provision agents, and tune each agent's widget settings. - name: Services description: The offerings your agents present and reason about. - name: Fit criteria description: What makes a good or poor lead — the signals your agents qualify against. - name: Voice profiles description: How your agents sound — tone, formality, phrasing. - name: Flow description: >- Author an agent's conversation — its phases and the answers each one captures. - name: Catalog description: >- Draft services, voice, and fit criteria from your knowledge, then accept or dismiss the proposals. paths: /knowledge_sources: post: tags: - Knowledge sources summary: Create or upsert a knowledge source description: > 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. operationId: createKnowledgeSource parameters: - name: Idempotency-Key in: header required: false schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/KnowledgeSourceCreate' responses: '200': description: >- Upserted an existing source (includes `body` for single-entry kinds). content: application/json: schema: $ref: '#/components/schemas/KnowledgeSource' '201': description: Created (includes `body` for single-entry kinds). content: application/json: schema: $ref: '#/components/schemas/KnowledgeSource' '401': $ref: '#/components/responses/Unauthorized' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/Invalid' '429': $ref: '#/components/responses/RateLimited' components: schemas: KnowledgeSourceCreate: type: object required: - kind properties: kind: type: string enum: - text - url - file - website title: type: string description: >- Required for text; optional for url/website (defaults to the host, upgraded by the page title) and file (defaults to the filename). body: type: string description: Required for text. Max 500,000 characters. url: type: string description: >- Required for url (the page) and website (the site root). http(s) only. max_pages: type: integer minimum: 1 maximum: 50 default: 30 description: 'website kind: page cap per refresh.' filename: type: string description: >- file kind: the original filename (extension decides the extractor: txt, md, pdf, docx). data: type: string description: 'file kind: strict base64 of the file, max 10MB decoded.' external_id: type: string maxLength: 255 description: Your sync key — unique per organization; makes POST an upsert. language: type: string description: Two-letter hint; detection at refresh may override. metadata: type: object additionalProperties: type: string description: >- Up to 20 string values (≤500 chars each). Returned verbatim, never interpreted. agents: type: array items: type: string description: >- Agent slugs this source is active for — declarative: the activation set becomes exactly this list. Omit to leave activations untouched. KnowledgeSource: type: object required: - object - id - kind - title - status - agents - metadata - entries - archived - created_at properties: object: type: string const: knowledge_source id: type: integer external_id: type: - string - 'null' kind: type: string enum: - text - url - file - website title: type: string url: type: - string - 'null' description: The page (url) or site root (website). status: type: string enum: - ready - updating - attention - failed description: > Aggregated from the source's entries: ready (everything ingested), updating (work in flight — poll), attention (usable with some failed entries), failed (nothing usable). failure_reason: type: - string - 'null' description: >- Single-entry kinds: why processing failed, human-readable. Websites report per-entry reasons under /entries. language: type: - string - 'null' digest: type: - string - 'null' description: >- What the agent understood from this source (generated after each refresh). agents: type: array items: type: string description: Slugs of the agents this source is active for. metadata: type: object additionalProperties: type: string entries: type: object description: Entry counts by status (one entry per page for websites). required: - total - ingested - pending - failed properties: total: type: integer ingested: type: integer pending: type: integer failed: type: integer max_pages: type: - integer - 'null' description: website kind only. archived: type: boolean created_at: type: string format: date-time last_update_at: type: - string - 'null' format: date-time description: When the last refresh run landed — the freshness stamp. body: type: string description: >- Full text. Present on retrieve/create/update for text/url/file; websites read per-page content via /entries. Error: type: object required: - error properties: error: type: object required: - type - code - message properties: type: type: string enum: - authentication_error - invalid_request_error - rate_limit_error - api_error code: type: string enum: - missing_api_key - invalid_api_key - resource_missing - method_not_allowed - resource_archived - idempotency_conflict - parameter_invalid - parameter_missing - parameter_unknown - organization_required - rate_limited - flow_invalid - internal message: type: string param: type: string responses: Unauthorized: description: Missing, malformed, or revoked API key. content: application/json: schema: $ref: '#/components/schemas/Error' Conflict: description: >- The resource is archived (restore it first), or the Idempotency-Key was reused with a different request. content: application/json: schema: $ref: '#/components/schemas/Error' Invalid: description: Validation failed — `error.param` names the field. content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your secret key (pep_sk_…) from Settings → API. Keys are org-scoped; treat them like passwords. ````