# Roark Docs

> Roark is the quality platform for voice and chat AI. Simulate every scenario before launch, monitor every production call, and score them with audio-native metrics.

- [Welcome to Roark](https://docs.roark.ai/documentation/getting-started/introduction.md): The quality platform for voice and chat AI
- [API Keys](https://docs.roark.ai/documentation/getting-started/api-keys.md): Generate and manage authentication keys for Roark APIs
- [Overview](https://docs.roark.ai/documentation/simulation-testing/overview.md): Pressure-test your voice AI agents before your customers do
- [Customer Flows](https://docs.roark.ai/documentation/simulation-testing/customer-flows.md): Define the customer conversations your agents should handle, and get graded against
- [Personas](https://docs.roark.ai/documentation/simulation-testing/personas.md): The callers your simulations run as
- [Environments](https://docs.roark.ai/documentation/simulation-testing/environments.md): The background noise a simulated customer calls from, and how loud it plays
- [Templates](https://docs.roark.ai/documentation/simulation-testing/templates.md): Start a simulation run from a goal: each template ships preset metrics, Pass/Fail checks, and its own configuration panel
- [Voicemail Testing](https://docs.roark.ai/documentation/simulation-testing/voicemail.md): Check that your agent notices it has reached voicemail, leaves a usable message, and hangs up
- [Run Plans](https://docs.roark.ai/documentation/simulation-testing/run-plans.md): Save simulation configurations as reusable test suites you can run on demand, on a schedule, or via API
- [Running Simulations](https://docs.roark.ai/documentation/simulation-testing/running-simulations.md): Trigger runs, watch them live, and read the settled report
- [Variables](https://docs.roark.ai/documentation/simulation-testing/variables.md): Feed dynamic values into customer flows and run plans with {{variable}} placeholders
- [Schedules](https://docs.roark.ai/documentation/simulation-testing/schedules.md): Put a plan on a schedule so it runs itself: hourly, daily, weekly, monthly, or once at a future time
- [CI/CD](https://docs.roark.ai/documentation/simulation-testing/ci-cd.md): Run simulations from your pipeline: sync your test suite with Config as Code and trigger a run on every change
- [Inbound vs Outbound](https://docs.roark.ai/documentation/simulation-testing/inbound-vs-outbound.md): Understanding simulation testing directions
- [WebRTC Simulations](https://docs.roark.ai/documentation/simulation-testing/webrtc.md): Run simulations over WebRTC instead of a phone line
- [Chat Simulations](https://docs.roark.ai/documentation/simulation-testing/chat-simulations.md): Test text-based AI agents the same way you test voice agents
- [Identifying Simulations](https://docs.roark.ai/documentation/simulation-testing/identifying-simulations.md): Verify simulation calls and retrieve simulation details from your agent
- [Enriched Simulations](https://docs.roark.ai/documentation/simulation-testing/enriched-simulations.md): Get richer call data in simulations by sending your agent call to Roark
- [Best Practices](https://docs.roark.ai/documentation/simulation-testing/best-practices.md): Guidelines for getting the most out of Roark simulations
- [Overview](https://docs.roark.ai/documentation/observability/overview.md): Monitor and analyze your voice AI conversations in real-time
- [Live Monitoring](https://docs.roark.ai/documentation/observability/live-monitoring.md): Browse, search, and analyze every voice AI call
- [Traces](https://docs.roark.ai/documentation/observability/traces.md): Send OpenTelemetry traces to Roark for full visibility into your Voice AI agent
- [Reports](https://docs.roark.ai/documentation/observability/reports.md): Analytics dashboards and insights for voice AI performance
- [Dashboards](https://docs.roark.ai/documentation/observability/dashboards.md): Organize multiple reports into a single view for comprehensive monitoring
- [Overview](https://docs.roark.ai/documentation/metrics/overview.md): Understand what metrics are and how to use them across monitoring and simulations
- [System Metrics Reference](https://docs.roark.ai/documentation/metrics/system-metrics.md): Complete reference for all built-in system metrics powered by specialized models
- [Custom Metrics](https://docs.roark.ai/documentation/metrics/custom-metrics.md): Create and manage custom metrics using LLM prompts, patterns, and formulas
- [Studio](https://docs.roark.ai/documentation/metrics/studio.md): Author, test, and evaluate metrics in one workbench before they run on live traffic
- [Collectors](https://docs.roark.ai/documentation/metrics/metric-collectors.md): Run a set of metrics automatically on every conversation that matches
- [Thresholds](https://docs.roark.ai/documentation/metrics/thresholds.md): Define pass/fail criteria for your metrics
- [Datasets](https://docs.roark.ai/documentation/metrics/datasets.md): Group calls or chats into named collections for evaluation, comparison, and analysis
- [Collection Jobs](https://docs.roark.ai/documentation/metrics/metric-collection-jobs.md): Run metrics on demand for specific calls via the API
- [Tool Invocations](https://docs.roark.ai/documentation/tool-invocations.md): Submit and track tool calls as part of post-call analysis
- [Overview](https://docs.roark.ai/documentation/config-as-code/overview.md): Define your Roark agents, personas, flows, metrics, collectors, and alerts as YAML in git and deploy them with one apply
- [Agents](https://docs.roark.ai/documentation/config-as-code/agents.md): Define voice agents as config
- [Personas](https://docs.roark.ai/documentation/config-as-code/personas.md): Define the simulated caller as config
- [Flows](https://docs.roark.ai/documentation/config-as-code/flows.md): Define simulation flows as config (improv and scripted)
- [Metrics](https://docs.roark.ai/documentation/config-as-code/metrics.md): Define custom LLM-judged metrics as config
- [Collectors](https://docs.roark.ai/documentation/config-as-code/collectors.md): Decide which metrics get collected on which conversations
- [Simulation plans](https://docs.roark.ai/documentation/config-as-code/simulation-plans.md): Declare a saved, repeatable simulation run
- [Alerts](https://docs.roark.ai/documentation/config-as-code/alerts.md): Define alerts (monitors) as config: threshold, event, and simulation triggers
- [Tool Call Testing](https://docs.roark.ai/documentation/recipes/tool-call-testing.md): Verify your agent calls the right tools with the right parameters
- [Accent Detection & TTS Drift Monitoring](https://docs.roark.ai/documentation/recipes/accent-detection.md): Detect accents and flag when your agent's TTS voice drifts mid-call
- [Testing Call Screeners](https://docs.roark.ai/documentation/recipes/call-screener-testing.md): Check your outbound agent recognises a gatekeeper, answers it directly, and saves its pitch for a person
- [Exporting to Snowflake](https://docs.roark.ai/documentation/integrations/exporting-to-snowflake.md): Sync your Roark call analysis into a data warehouse to join it against your own operational data
- [Overview](https://docs.roark.ai/documentation/integrations/overview.md): Every platform Roark connects to, and exactly which capabilities each one supports
- [VAPI](https://docs.roark.ai/documentation/integrations/vapi.md): Sync VAPI assistants and analyze voice AI conversations
- [Pipecat](https://docs.roark.ai/documentation/integrations/pipecat.md): Instrument a Pipecat voice agent with the roark_analytics[pipecat] observer, self-hosted or on Pipecat Cloud
- [Retell AI](https://docs.roark.ai/documentation/integrations/retell.md): Sync Retell agents and analyze voice AI conversations
- [ElevenLabs](https://docs.roark.ai/documentation/integrations/elevenlabs.md): Sync ElevenLabs conversational AI agents and run voice and chat simulations
- [Leaping](https://docs.roark.ai/documentation/integrations/leaping.md): Sync Leaping AI agents and analyze voice conversations
- [LiveKit Cloud](https://docs.roark.ai/documentation/integrations/livekit.md): Connect LiveKit Cloud for real-time voice communication monitoring
- [LiveKit (self-hosted)](https://docs.roark.ai/documentation/integrations/livekit-self-hosted.md): Instrument a self-hosted LiveKit Agents worker with the roark-analytics[livekit] SDK
- [Bland AI](https://docs.roark.ai/documentation/integrations/bland.md): Sync Bland AI agents and analyze voice AI conversations
- [Google CES](https://docs.roark.ai/documentation/integrations/google-ces.md): Run chat simulations against Google Customer Engagement Suite apps
- [Kore AI](https://docs.roark.ai/documentation/integrations/kore.md): Run chat simulations against Kore AI Agent Platform apps
- [Custom Integrations](https://docs.roark.ai/documentation/integrations/custom-integrations.md): Send calls from any platform using our API and SDKs
- [Okta SSO + SCIM](https://docs.roark.ai/documentation/integrations/okta.md): Sign your team into Roark with Okta, and optionally push-provision and deprovision users via SCIM
- [IP Whitelisting](https://docs.roark.ai/documentation/integrations/ip-whitelisting.md): Whitelist Roark Analytics production IPs for firewalls, webhooks, and presigned URLs
- [Data Retention](https://docs.roark.ai/documentation/enterprise/data-retention.md): Control how long Roark keeps your call data, and whether expired data is hidden or permanently deleted
- [PII Redaction](https://docs.roark.ai/documentation/observability/pii-redaction.md): Mask sensitive caller information in transcripts before it reaches your team or evaluators
- [CLI](https://docs.roark.ai/documentation/sdks/cli.md): Drive Roark from your terminal and your CI pipeline
- [Node.js SDK](https://docs.roark.ai/documentation/sdks/node-sdk.md): Upload calls, run metrics, and execute simulations using Node.js
- [Python SDK](https://docs.roark.ai/documentation/sdks/python-sdk.md): Upload calls, run metrics, and execute simulations using Python
- [MCP Server](https://docs.roark.ai/documentation/sdks/mcp-server.md): Connect AI agents and coding assistants to the Roark API using the Model Context Protocol
- [Agent Skills](https://docs.roark.ai/documentation/sdks/skills.md): Teach any coding agent to test voice and chat AI agents with Roark
- [Webhooks](https://docs.roark.ai/documentation/integrations/webhooks.md): Receive real-time notifications when call analysis completes or fails
- [Support](https://docs.roark.ai/documentation/resources/support.md): Get help with Roark
- [Glossary](https://docs.roark.ai/documentation/resources/glossary.md): Key terms and concepts used in Roark
- [Troubleshooting](https://docs.roark.ai/documentation/resources/troubleshooting.md): Solutions to common issues when using Roark
- [Introduction](https://docs.roark.ai/api-reference/introduction.md): Integrating with the Roark API
- [Authorization](https://docs.roark.ai/api-reference/authorization.md): How to authenticate API requests
- [Get API health status](https://docs.roark.ai/api-reference/health/get-api-health-status.md): Returns the health status of the API and its dependencies
- [Exchange a CLI authorization code for an API key](https://docs.roark.ai/api-reference/cli-auth/exchange-a-cli-authorization-code-for-an-api-key.md): Completes the CLI browser-login flow: verifies the single-use authorization code and its PKCE code_verifier, then mints and returns the approved API key exactly once.
- [List agent endpoints](https://docs.roark.ai/api-reference/agent-endpoint/list-agent-endpoints.md): Returns a paginated list of agent endpoints for the authenticated project.
- [Create a new agent endpoint](https://docs.roark.ai/api-reference/agent-endpoint/create-a-new-agent-endpoint.md): Creates a new agent endpoint for the authenticated project.
- [Get agent endpoint by ID](https://docs.roark.ai/api-reference/agent-endpoint/get-agent-endpoint-by-id.md): Returns a specific agent endpoint by its ID.
- [Update an agent endpoint](https://docs.roark.ai/api-reference/agent-endpoint/update-an-agent-endpoint.md): Updates an existing agent endpoint by its ID. Only environment and outboundDialType can be modified.
- [List an agent's prompts](https://docs.roark.ai/api-reference/agent/list-an-agents-prompts.md): Returns the agent's prompt lineages. Each lineage is an independent version history, labelled by its `source` (USER, API, CONFIG, or a provider integration). `prompt` is the current content.
- [Set an agent's prompt](https://docs.roark.ai/api-reference/agent/set-an-agents-prompt.md): Sets the agent's API-managed prompt. This is its own version history (`source: API_MANAGED`), separate from prompts observed on calls, edited in the app, or managed by config-as-code. Setting the same content twice is a no-op (no new version). Roark does not run your agent and no metric reads this p…
- [List a prompt's versions](https://docs.roark.ai/api-reference/agent/list-a-prompts-versions.md): Returns the full version history of a single prompt lineage, newest first.
- [List agents](https://docs.roark.ai/api-reference/agent/list-agents.md): Returns a paginated list of agents for the authenticated project.
- [Create a new agent](https://docs.roark.ai/api-reference/agent/create-a-new-agent.md): Creates a new agent for the authenticated project.
- [Get agent by ID](https://docs.roark.ai/api-reference/agent/get-agent-by-id.md): Returns a specific agent by its ID.
- [Update an agent](https://docs.roark.ai/api-reference/agent/update-an-agent.md): Updates an existing agent by its ID.
- [Delete an agent](https://docs.roark.ai/api-reference/agent/delete-an-agent.md): Soft-deletes an agent by its ID. The agent is hidden from all reads and stops being attributed to new calls, but its record and history are retained. Fails with 409 if the agent is still referenced by simulation run plans: cancel those run plans first. Note: if the agent syncs from a provider integr…
- [List calls](https://docs.roark.ai/api-reference/call/list-calls.md): Returns a paginated list of calls for the authenticated project.
- [Create a call](https://docs.roark.ai/api-reference/call/create-a-call.md): Create a new call with recording, transcript, agents, and customers
- [Get a call by ID](https://docs.roark.ai/api-reference/call/get-a-call-by-id.md): Retrieve an existing call by its unique identifier
- [List call sentiment runs](https://docs.roark.ai/api-reference/call/list-call-sentiment-runs.md): Fetch detailed sentiment analysis results for a specific call, including emotional tone, key phrases, and sentiment scores.
- [List call metrics](https://docs.roark.ai/api-reference/call/list-call-metrics.md): Fetch all call-level metrics for a specific call, including both system-generated and custom metrics. Only returns rows from the **latest** metric-collection job per metric — if the same metric has been recomputed, prior runs are excluded and remain in the metric history. By default returns only suc…
- [Get call transcript](https://docs.roark.ai/api-reference/call/get-call-transcript.md): Fetch the full transcript for a specific call. Optionally specify a transcription source; otherwise the best available source is used automatically.
- [Append tool invocations to a call](https://docs.roark.ai/api-reference/call/append-tool-invocations-to-a-call.md): Attach tool invocations that fired during a call to an already-existing call, asynchronously after the call was created. Use this when the tool-call data becomes available later than the call itself (e.g. a Roark simulation, or a call submitted via POST /v1/call before its tools were ready). Writes…
- [List chats](https://docs.roark.ai/api-reference/chat/list-chats.md): Returns a paginated list of chats for the authenticated project.
- [Create a chat](https://docs.roark.ai/api-reference/chat/create-a-chat.md): Create a new chat with segments (messages and tool invocations)
- [Get a chat by ID](https://docs.roark.ai/api-reference/chat/get-a-chat-by-id.md): Retrieve an existing chat by its unique identifier
- [Get chat transcript](https://docs.roark.ai/api-reference/chat/get-chat-transcript.md): Fetch the full transcript (messages) for a specific chat.
- [List chat metrics](https://docs.roark.ai/api-reference/chat/list-chat-metrics.md): Fetch all metrics for a specific chat, including both system-generated and custom metrics. Only returns rows from the **latest** metric-collection job per metric — if the same metric has been recomputed, prior runs are excluded and remain in the metric history. By default returns only successfully c…
- [List metric definitions](https://docs.roark.ai/api-reference/metric/list-metric-definitions.md): Fetch metric definitions available in the project, including both system-generated and custom metrics. Results are ordered by immutable definition ID; pass `nextCursor` to retrieve the following page.
- [Create custom metric definition](https://docs.roark.ai/api-reference/metric/create-custom-metric-definition.md): Create a new metric definition. The `calculationType` field selects the variant: LLM_JUDGE (LLM-evaluated), FORMULA (computed from a math expression over other metrics), or PATTERN (detects a trigger→outcome pattern within a window). To create a threshold on top of an existing metric, use `POST /met…
- [Get a metric definition](https://docs.roark.ai/api-reference/metric/get-a-metric-definition.md): Fetch a single metric definition by its UUID or its stable `slug` (e.g. `customer_satisfaction`). Resolution is scoped to the project — a project-owned metric wins over an org-wide one, which wins over a system metric of the same `slug`.
- [Update a metric definition](https://docs.roark.ai/api-reference/metric/update-a-metric-definition.md): Update the editable subset of a custom metric definition, addressed by its UUID or its stable `slug`. Only the supplied fields are changed; omitted fields are left unchanged. Every update creates a new immutable version; the response carries the advanced `versionId`. Immutable fields (scope, outputT…
- [Delete a metric definition](https://docs.roark.ai/api-reference/metric/delete-a-metric-definition.md): Archives (soft-deletes) a custom metric definition, addressed by its UUID or its stable `slug`. The metric is hidden from all reads and stops being collected, but its record and previously collected values are retained. System metrics cannot be deleted. Fails with 409 if the metric is still used as…
- [Create a threshold on a metric](https://docs.roark.ai/api-reference/metric/create-a-threshold-on-a-metric.md): Create a boolean threshold derived from an existing metric. The source metric is addressed by its UUID or its stable `slug`. The threshold fires when the source metric meets the comparison condition. Scope and supported contexts are inherited from the source metric.
- [List a metric’s variants](https://docs.roark.ai/api-reference/metric/list-a-metric’s-variants.md): Every configuration of this metric your organization can use: Roark’s own variants and any your organization has added or forked. `isDefault` marks the one the metric is scored with when nothing pins another; pass any variant’s `id` as `sourceVariantId` to pin it on a derived metric.
- [Create a metric variant](https://docs.roark.ai/api-reference/metric/create-a-metric-variant.md): Add a configuration of this metric for your organization, seeded from its Default. Edit it with PUT to change what it measures, then pin it where you want it used.
- [Get a metric variant](https://docs.roark.ai/api-reference/metric/get-a-metric-variant.md): One configuration of this metric, by id.
- [Update a metric variant](https://docs.roark.ai/api-reference/metric/update-a-metric-variant.md): Rename a variant, change its configuration, or both. Every configuration change creates a new immutable version and advances `versionId`; the response carries the advanced value.
- [Delete a metric variant](https://docs.roark.ai/api-reference/metric/delete-a-metric-variant.md): Remove one of your organization’s variants. Anything pinned to it falls back to the Default, so deleting a fork of a Roark variant returns you to Roark’s configuration.
- [List metric policies](https://docs.roark.ai/api-reference/metric-policy/list-metric-policies.md): Returns a paginated list of metric policies for the project, including system policies.
- [Create a metric policy](https://docs.roark.ai/api-reference/metric-policy/create-a-metric-policy.md): Creates a new metric policy. Policies define which metrics to collect and under what conditions.
- [Get metric policy by ID](https://docs.roark.ai/api-reference/metric-policy/get-metric-policy-by-id.md): Returns a specific metric policy with its conditions and metrics.
- [Update a metric policy](https://docs.roark.ai/api-reference/metric-policy/update-a-metric-policy.md): Updates an existing metric policy. System policies cannot be modified.
- [Delete a metric policy](https://docs.roark.ai/api-reference/metric-policy/delete-a-metric-policy.md): Soft-deletes a metric policy. System policies cannot be deleted.
- [List metric collection jobs](https://docs.roark.ai/api-reference/metric-collection-job/list-metric-collection-jobs.md): Returns a paginated list of metric collection jobs for the project.
- [Create and run a metric collection job](https://docs.roark.ai/api-reference/metric-collection-job/create-and-run-a-metric-collection-job.md): Creates a metric collection job for the specified calls or chats and metrics, then triggers processing. Provide exactly one of callIds or chatIds.
- [Get metric collection job by ID](https://docs.roark.ai/api-reference/metric-collection-job/get-metric-collection-job-by-id.md): Returns a specific metric collection job with progress information.
- [Retry a metric collection job](https://docs.roark.ai/api-reference/metric-collection-job/retry-a-metric-collection-job.md): Creates a new metric collection job using the same conversations and metrics as a previous job, then triggers processing. The previous job must be in a terminal state (COMPLETED, FAILED, or CANCELED). Returns the newly created job — track its id for downstream fetches.
- [Get metric values produced by a metric collection job](https://docs.roark.ai/api-reference/metric-collection-job/get-metric-values-produced-by-a-metric-collection-job.md): Returns the metric values produced by the specified job, grouped by metric definition. Unlike `GET /v1/call/:callId/metrics` (which returns the latest values on a call, regardless of which job computed them), this endpoint returns exactly the values *this* job produced — including for calls whose li…
- [List personas](https://docs.roark.ai/api-reference/simulation-persona/list-personas.md): Returns a paginated list of personas for the authenticated project.
- [Create a new persona](https://docs.roark.ai/api-reference/simulation-persona/create-a-new-persona.md): Creates a new persona for the authenticated project.
- [Get persona by ID](https://docs.roark.ai/api-reference/simulation-persona/get-persona-by-id.md): Returns a specific persona by its ID.
- [Update a persona](https://docs.roark.ai/api-reference/simulation-persona/update-a-persona.md): Updates an existing persona by its ID.
- [Delete a persona](https://docs.roark.ai/api-reference/simulation-persona/delete-a-persona.md): Soft-deletes a persona by its ID. The persona is hidden from all reads and stops being available to new simulations, but its record and history are retained. System personas cannot be deleted.
- [Run a simulation](https://docs.roark.ai/api-reference/simulation/run-a-simulation.md): Starts a simulation and returns the run.
- [List environments](https://docs.roark.ai/api-reference/simulation-environment/list-environments.md): Returns a paginated list of environments: the project's own plus the environments Roark curates and shares across every project. Reference one by id when setting a customer flow variant's environment.
- [Create an environment](https://docs.roark.ai/api-reference/simulation-environment/create-an-environment.md): Creates an environment for the project: a noise bed and the level it plays at. Reference it by id when setting a customer flow variant's environment. Roark's curated presets always play at the default level, so this is how a project gets the same bed louder or quieter.
- [Get environment by ID](https://docs.roark.ai/api-reference/simulation-environment/get-environment-by-id.md): Returns a single environment by its ID.
- [Update an environment](https://docs.roark.ai/api-reference/simulation-environment/update-an-environment.md): Updates one of the project's environments. Only the fields sent are changed. Runs already built keep the snapshot they were built with. Roark-curated environments cannot be edited (403).
- [Delete an environment](https://docs.roark.ai/api-reference/simulation-environment/delete-an-environment.md): Soft-deletes one of the project's environments. It disappears from reads and cannot be picked for new runs; runs already built keep their snapshot. Refused (409) while a live customer flow variant still uses it: move those variants first. Roark-curated environments cannot be deleted (403).
- [List run plans](https://docs.roark.ai/api-reference/simulation-run-plan/list-run-plans.md): Returns a paginated list of simulation run plans. Optionally filter by search text or agent ID.
- [Create a run plan](https://docs.roark.ai/api-reference/simulation-run-plan/create-a-run-plan.md): Creates a new simulation run plan.
- [Get run plan by ID](https://docs.roark.ai/api-reference/simulation-run-plan/get-run-plan-by-id.md): Returns a specific simulation run plan by its ID.
- [Update a run plan](https://docs.roark.ai/api-reference/simulation-run-plan/update-a-run-plan.md): Updates an existing simulation run plan by its ID.
- [Delete a run plan](https://docs.roark.ai/api-reference/simulation-run-plan/delete-a-run-plan.md): Soft-deletes a simulation run plan by its ID.
- [List simulation plan jobs](https://docs.roark.ai/api-reference/simulation-run-plan-job/list-simulation-plan-jobs.md): Returns a paginated list of simulation run plan jobs. Filter by status, plan ID, or label to find specific simulation batches.
- [Get simulation plan job](https://docs.roark.ai/api-reference/simulation-run-plan-job/get-simulation-plan-job.md): Retrieve details of a simulation plan job including all associated simulation jobs (calls)
- [Run a simulation plan](https://docs.roark.ai/api-reference/simulation-run-plan-job/run-a-simulation-plan.md): Deprecated: use POST /v1/simulation/run, which does the same thing and can also take the plan configuration inline, so a one-off run does not have to create a plan first.
- [List simulation templates](https://docs.roark.ai/api-reference/simulation-template/list-simulation-templates.md): Returns the built-in simulation templates, each resolved against this project: the metric and check definitions it collects, and the flows it runs with the variants it covers.
- [Lookup by phone number](https://docs.roark.ai/api-reference/simulation-job/lookup-by-phone-number.md): Find the matching simulation using the number used by the Roark simulation agent.
- [Get simulation by ID](https://docs.roark.ai/api-reference/simulation-job/get-simulation-by-id.md): Get a individual simulation run directly by its ID. This is generally part of a larger simulation run plan job.
- [List customer flows](https://docs.roark.ai/api-reference/customer-flow/list-customer-flows.md): Returns a paginated list of customer flows with their agents, expectations, happy path and edge cases. The step graph is the one field omitted: reading it walks the project's whole step graph, so it comes back from the single-flow endpoint instead. Customer flows are how a project describes what to…
- [Create a customer flow](https://docs.roark.ai/api-reference/customer-flow/create-a-customer-flow.md): Creates a customer flow. A SCRIPTED flow carries a step graph and gets one way of running it per path through the graph; an IMPROV flow carries the briefs you send. Customer flows replace the older simulation scenarios, so build a flow for anything new.
- [Get customer flow by ID](https://docs.roark.ai/api-reference/customer-flow/get-customer-flow-by-id.md): Returns a customer flow with its happy path, edge cases, expectations and linked agents. Scripted flows also carry their step graph.
- [Update a customer flow](https://docs.roark.ai/api-reference/customer-flow/update-a-customer-flow.md): Updates a flow's title, description, branching mode, linked agents or flow-level expectations. The step graph is replaced through PUT /graph.
- [Delete a customer flow](https://docs.roark.ai/api-reference/customer-flow/delete-a-customer-flow.md): Soft-deletes a customer flow along with its edge cases, expectations and (for scripted flows) its step graph. Run plans that linked it drop it from their test cases.
- [Replace a scripted flow's steps](https://docs.roark.ai/api-reference/customer-flow/replace-a-scripted-flows-steps.md): Replaces a scripted flow's conversation graph with the tree you send. This is a full replace, not a merge: a step you omit is removed.
- [Update a flow's happy path](https://docs.roark.ai/api-reference/customer-flow/update-a-flows-happy-path.md): Updates the happy path's title, persona, environment, brief or expectations. Omitted fields are left alone; `additionalExpectations` replaces the set wholesale rather than appending.
- [Duplicate a customer flow](https://docs.roark.ai/api-reference/customer-flow/duplicate-a-customer-flow.md): Deep-copies a flow into a new project-owned flow. The copy carries the source's description, branching mode, linked agents, flow-level expectations and flow-owned metrics. A scripted flow copies its whole step graph; an improv flow copies its variants (personas, briefs, expectations). Duplicating a…
- [Add an edge case](https://docs.roark.ai/api-reference/customer-flow-edge-case/add-an-edge-case.md): Adds a variant to an IMPROV flow.
- [Update an edge case](https://docs.roark.ai/api-reference/customer-flow-edge-case/update-an-edge-case.md): Updates an edge case's title, persona, environment, brief, preceded-by link or expectations. Omitted fields are left alone; `additionalExpectations` replaces the set wholesale rather than appending. Promoting it to the happy path is a separate call, since that also demotes the incumbent.
- [Remove an edge case](https://docs.roark.ai/api-reference/customer-flow-edge-case/remove-an-edge-case.md): Soft-deletes a variant. On a scripted flow the path engine re-creates a variant for any path still in the graph, so remove the path through PUT /graph instead if that is what you meant.
- [Promote an edge case to the happy path](https://docs.roark.ai/api-reference/customer-flow-edge-case/promote-an-edge-case-to-the-happy-path.md): Makes this edge case the flow's happy path, and the outgoing happy path an edge case. Its persona and environment are baked into it first, so edge cases that were inheriting keep the configuration they had.
- [List HTTP request definitions](https://docs.roark.ai/api-reference/http-request-definition/list-http-request-definitions.md): Returns a paginated list of HTTP request definitions for the authenticated project.
- [Create HTTP request definition](https://docs.roark.ai/api-reference/http-request-definition/create-http-request-definition.md): Creates a new HTTP request definition. The signing secret is only returned in this response and cannot be retrieved later.
- [Get HTTP request definition by ID](https://docs.roark.ai/api-reference/http-request-definition/get-http-request-definition-by-id.md): Returns a specific HTTP request definition by its ID.
- [Update HTTP request definition](https://docs.roark.ai/api-reference/http-request-definition/update-http-request-definition.md): Updates an existing HTTP request definition.
- [List webhooks](https://docs.roark.ai/api-reference/webhook/list-webhooks.md): Returns a paginated list of webhooks with their event subscriptions.
- [Create webhook](https://docs.roark.ai/api-reference/webhook/create-webhook.md): Creates a new webhook with event subscriptions. The signing secret is only returned in this response.
- [Get webhook by ID](https://docs.roark.ai/api-reference/webhook/get-webhook-by-id.md): Returns a specific webhook with its event subscriptions.
- [Delete webhook](https://docs.roark.ai/api-reference/webhook/delete-webhook.md): Deletes a webhook and all its event subscriptions.
- [Event](https://docs.roark.ai/api-reference/webhook/event.md): Roark POSTs a JSON payload to every endpoint subscribed to one of the events listed below. Every payload uses the same envelope (`event`, `version`, `timestamp`, `data`); the `event` field is the discriminator that selects the matching `data` shape.
- [List issues](https://docs.roark.ai/api-reference/issue/list-issues.md): Returns the project’s issues, ordered newest-first. Supports filtering by status, source, and severity, with offset pagination.
- [Create issue](https://docs.roark.ai/api-reference/issue/create-issue.md): Opens a new issue with `source: API`. The supplied evidence (calls / chats) is attached in the same transaction; an invalid reference fails the whole request rather than leaving a half-created issue.
- [Get issue by ID](https://docs.roark.ai/api-reference/issue/get-issue-by-id.md): Returns a single issue with its evidence rows.
- [List knowledge bases](https://docs.roark.ai/api-reference/knowledge-base/list-knowledge-bases.md): Returns a cursor-paginated list of knowledge bases for the authenticated project. Soft-deleted knowledge bases are excluded.
- [Create a knowledge base](https://docs.roark.ai/api-reference/knowledge-base/create-a-knowledge-base.md): Creates a knowledge base. TEXT and JSON sources accept inline `content`. FILE sources require `filename`, `mimeType`, and base64-encoded `contentBase64` — the file is decoded server-side, stored in S3, and (for PDFs) text-extracted inline before the response returns.
- [Get a knowledge base by ID](https://docs.roark.ai/api-reference/knowledge-base/get-a-knowledge-base-by-id.md): Returns metadata for a single knowledge base. Does not include content — content is read by metrics at evaluation time and is not exposed over the public API.
- [Diff a config bundle](https://docs.roark.ai/api-reference/config/diff-a-config-bundle.md): Dry run for a config-as-code apply: returns the projected changes (create / update / delete) for the submitted bundle without writing anything. Submit the full desired set of resources; identity is by name — no ids in the bundle. Run this before apply to preview what would change.
- [Apply a config bundle](https://docs.roark.ai/api-reference/config/apply-a-config-bundle.md): Reconcile a config-as-code bundle into the project. Submit the full desired set of resources; resources already managed by config are updated, new ones created, and (unless prune is false) config-managed resources absent from the bundle are deleted. Identity is by name — no ids in the bundle.

## OpenAPI Specs

- [openapi.documented](/api-reference/openapi.documented.json)

## Optional

- [Changelog](https://changelog.roark.ai)