# pepline API

## Docs

- [List agents](https://docs.pepline.ai/api-reference/agents/list-agents.md): Cursor-paginated, newest first. Archived agents are excluded.
- [Provision an agent](https://docs.pepline.ai/api-reference/agents/provision-an-agent.md): Clones a catalog starter (SPEC-LAUNCH provisioning): flow, prompts, deliverable templates, widget defaults. The new agent starts PAUSED with empty knowledge/fit activations. Flow authoring is deliberately NOT part of the API.
- [Retrieve an agent's widget settings](https://docs.pepline.ai/api-reference/agents/retrieve-an-agents-widget-settings.md)
- [Update an agent's widget settings](https://docs.pepline.ai/api-reference/agents/update-an-agents-widget-settings.md): Runtime knobs — changes serve immediately. `translations` merges field-by-field per locale (partial payloads never clobber sibling fields); everything else replaces what it names.
- [Accept a proposal](https://docs.pepline.ai/api-reference/catalog/accept-a-proposal.md): Creates the real catalog row through the same authoring path the dashboard uses (identical validations). Idempotent — an already-accepted draft stays accepted.
- [Dismiss a proposal](https://docs.pepline.ai/api-reference/catalog/dismiss-a-proposal.md): Marks the proposal dismissed. Dismissal is permanent per fingerprint: a later regeneration never re-proposes it.
- [List config proposals](https://docs.pepline.ai/api-reference/catalog/list-config-proposals.md): The proposals a regeneration (or onboarding) produced. Filter by `kind`, `status`, or the `catalog_generation_id` that produced them.
- [Poll a regeneration run](https://docs.pepline.ai/api-reference/catalog/poll-a-regeneration-run.md): The run's status (`running`, `completed`, `attention`, `failed`) and per-kind result (proposed count, and — for services — the completeness self-check's `expected`/`covered`/`note`). `attention` means the material looks like it names more than got drafted.
- [Regenerate a catalog from knowledge](https://docs.pepline.ai/api-reference/catalog/regenerate-a-catalog-from-knowledge.md): Re-draft one catalog `kind` (service, voice, fit_criterion) from the organization's knowledge, forced past the no-nag gate that normally skips an already-configured catalog. Additive: it proposes only the genuinely missing items (deduped against what already exists) and never writes to the live cata…
- [Create a fit criterion](https://docs.pepline.ai/api-reference/fit-criteria/create-a-fit-criterion.md): Without `agents`, the criterion activates for ALL current agents (the dashboard's default). With `agents`, exactly those.
- [List fit criteria](https://docs.pepline.ai/api-reference/fit-criteria/list-fit-criteria.md)
- [Update a fit criterion](https://docs.pepline.ai/api-reference/fit-criteria/update-a-fit-criterion.md)
- [Add a slot (chip) to a phase](https://docs.pepline.ai/api-reference/flow/add-a-slot-chip-to-a-phase.md): Adds a slot — the data contract of the phase and, for enum/band types, the quick-reply chips. `key` must be lowercase letters/digits/underscores; `enum_values` is required for enum/band. Trial-compiles; 422 if it overflows the 16-slot schema budget.
- [Archive a phase](https://docs.pepline.ai/api-reference/flow/archive-a-phase.md)
- [Archive a slot](https://docs.pepline.ai/api-reference/flow/archive-a-slot.md)
- [Author a phase](https://docs.pepline.ai/api-reference/flow/author-a-phase.md): Adds a phase (step kind) before the trailing terminal state. The key is minted from the title once (identity afterwards). Trial-compiles; 422 on a compile-budget or reserved-key violation.
- [Edit a phase (prose and tools)](https://docs.pepline.ai/api-reference/flow/edit-a-phase-prose-and-tools.md): Updates the phase's title, objective, exit_criteria, max_turns, and/or tools. Trial-compiles.
- [Edit a slot (chip)](https://docs.pepline.ai/api-reference/flow/edit-a-slot-chip.md): Updates the slot's title, data_type, required, description, enum_values, enum_labels, or translations. Trial-compiles.
- [Get an agent's conversation flow](https://docs.pepline.ai/api-reference/flow/get-an-agents-conversation-flow.md): The agent's active flow — its phases and each phase's slots (the chips a visitor sees). The structural vocabulary (kind, tools, exits, transitions, guards) is read-only; author phases and slots via the endpoints below.
- [Reorder a phase](https://docs.pepline.ai/api-reference/flow/reorder-a-phase.md): Moves a phase one place earlier (`up`) or later (`down`), swapping it with its neighbour among the live phases. A new phase always lands just before the closing phase, so this is how you place it. The closing phase stays last and nothing moves past it — attempting either is a 422, as is moving beyon…
- [Restore a phase](https://docs.pepline.ai/api-reference/flow/restore-a-phase.md)
- [Restore a slot](https://docs.pepline.ai/api-reference/flow/restore-a-slot.md)
- [Archive a source](https://docs.pepline.ai/api-reference/knowledge-sources/archive-a-source.md): The source leaves every agent's knowledge immediately but keeps its history. Idempotent.
- [Create or upsert a knowledge source](https://docs.pepline.ai/api-reference/knowledge-sources/create-or-upsert-a-knowledge-source.md): 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 updat…
- [List a source's entries](https://docs.pepline.ai/api-reference/knowledge-sources/list-a-sources-entries.md): The page-grained truth beneath an origin: one entry per crawled page for website sources, exactly one for text/url/file. Read-only — content arrives through the source. Cursor-paginated, newest first.
- [List a source's update runs](https://docs.pepline.ai/api-reference/knowledge-sources/list-a-sources-update-runs.md): The source's run history: when it was refreshed, by what trigger (manual, api), and the run's stats (pages discovered, added/updated counts, discovery method, duration). Cursor-paginated, newest first.
- [List knowledge sources](https://docs.pepline.ai/api-reference/knowledge-sources/list-knowledge-sources.md): Cursor-paginated, newest first. `body` is omitted on list — retrieve a single source for the full text. Archived sources are excluded unless `archived=true`.
- [Not supported — archive instead](https://docs.pepline.ai/api-reference/knowledge-sources/not-supported-—-archive-instead.md): Sources are never destroyed (history preservation). This answers 405 and points at the archive endpoint.
- [Refresh a source](https://docs.pepline.ai/api-reference/knowledge-sources/refresh-a-source.md): One verb for every kind: re-fetches the page (`url`), re-discovers and re-fetches the site's pages (`website`), re-processes the stored content (`text`/`file`). Asynchronous — 202 with the source in `updating`; poll the source until `ready`, `attention` or `failed`. Every refresh writes an update ru…
- [Restore an archived source](https://docs.pepline.ai/api-reference/knowledge-sources/restore-an-archived-source.md): Brings the source back into its agents' knowledge. Idempotent.
- [Retrieve a knowledge source](https://docs.pepline.ai/api-reference/knowledge-sources/retrieve-a-knowledge-source.md): Includes `body` (single-entry kinds), `digest`, entry counts and freshness. Poll this after creates and refreshes until `status` is `ready`, `attention` or `failed`.
- [Update a knowledge source](https://docs.pepline.ai/api-reference/knowledge-sources/update-a-knowledge-source.md): Edits `title`, `language`, `metadata`, `agents` — plus `body` on text sources (other kinds re-fetch via refresh instead) and `max_pages` on website sources. Body changes refresh the source.
- [Retrieve your organization](https://docs.pepline.ai/api-reference/organization/retrieve-your-organization.md): The canonical "is my key working" call. Also lists your agent slugs for the `agents` field on sources.
- [Create a service](https://docs.pepline.ai/api-reference/services/create-a-service.md): `key` is minted from the name when omitted (lowercase + underscores — it names the synthesis enum entry and never changes). `agents` is a declarative activation set: the service is offered by exactly the agents listed.
- [List services](https://docs.pepline.ai/api-reference/services/list-services.md)
- [Update a service](https://docs.pepline.ai/api-reference/services/update-a-service.md): `key` is identity and cannot change. `agents`, when present, replaces the activation set.
- [Create a voice profile](https://docs.pepline.ai/api-reference/voice-profiles/create-a-voice-profile.md): Voice is SELECTION, not activation: `agents` points each listed agent at THIS profile (an agent leaves a voice by being claimed by another, never by omission).
- [List voice profiles](https://docs.pepline.ai/api-reference/voice-profiles/list-voice-profiles.md)
- [Update a voice profile](https://docs.pepline.ai/api-reference/voice-profiles/update-a-voice-profile.md)
- [Authentication](https://docs.pepline.ai/authentication.md): Bearer secret keys, org-scoped, revocable.
- [Agents and catalog](https://docs.pepline.ai/authoring/agents-and-catalog.md): Provision agents from a starter, then shape how they sell, qualify, and sound.
- [Conversation flows](https://docs.pepline.ai/authoring/conversation-flows.md): Read and author an agent's conversation — its phases and the answers each one captures.
- [Drafting from knowledge](https://docs.pepline.ai/authoring/drafting-from-knowledge.md): Let pepline propose services, voice, and fit criteria from what your agents already know.
- [The authoring API](https://docs.pepline.ai/authoring/overview.md): Provision and shape agents from your own systems — the same config surface the dashboard uses.
- [Errors](https://docs.pepline.ai/errors.md): One envelope, typed codes, a param when a field is to blame.
- [Keeping knowledge fresh](https://docs.pepline.ai/guides/keeping-knowledge-fresh.md): One source per origin — sync it with external_id upserts, bring in whole websites, refresh anything with one verb.
- [Introduction](https://docs.pepline.ai/index.md): Push knowledge into your pepline agents from anywhere.
- [Pagination](https://docs.pepline.ai/pagination.md): Cursor pagination, stable under concurrent writes.
- [Quickstart](https://docs.pepline.ai/quickstart.md): First knowledge pushed in five minutes.
- [Versioning](https://docs.pepline.ai/versioning.md): Path-versioned; additive changes ship freely, breaking changes make a new version.

## OpenAPI Specs

- [openapi](https://app.pepline.ai/api/v1/openapi.yaml)