Config as Code

Overview

Config as Code lets you define your Roark resources - agents, personas, simulation flows, and metric collectors - as YAML files in your own git repository, then deploy them with a single apply. Your config repo is the source of truth: Roark reconciles the live project to match what you submitted, creating what’s new, updating what changed, and removing what you deleted.

Config as Code manages resource definitions. It does not run simulations or place calls; you trigger those as usual once the resources exist.

You write only a human-readable name for each resource. Roark derives a stable identity (configKey = <kind>/<name>) and resolves cross-references by name, so there are no UUIDs in your files and no state file to keep in sync.

How it works

You submit the full desired set of resources to a single endpoint. Roark:

Parses and validates every resource against the schema.
Diffs the submitted set against the resources this project already manages via config.
Reconciles: creates new resources, updates changed ones, and (unless you opt out) deletes config-managed resources you removed from the submission.

There are two endpoints:

Endpoint	What it does
`POST /v1/config/plan`	Dry run. Returns the changes that would be made. No writes.
`POST /v1/config/apply`	Applies the changes and returns what happened.

Always run plan first to preview the diff, then apply.

Prerequisites

A Roark API key with the config:apply permission. Generate one from API Keys and confirm it carries config:apply.
A git repository to hold your config files (any layout; Roark reads the files you submit).

The API key is scoped to a single project. Everything you apply lands in that project.

Repository layout

One file per resource, discriminated by kind. A conventional layout:

roark/
  agents/frontdesk.yaml
  personas/frustrated-caller.yaml
  flows/frustrated-rebooking.yaml     # improv flow
  flows/booking-scripted.yaml         # scripted-graph flow
  collectors/consent-on-frontdesk.yaml
  prompts/escalates-to-manager.md     # referenced by file://

Add this header to any resource file for editor autocomplete and validation:

# yaml-language-server: $schema=https://schema.roark.ai/roark-config.schema.json

Resource kinds

Agent

kind: agent
name: frontdesk
description: Bright Smiles front desk booking agent
customId: bright-smiles-frontdesk
endpoints:
  - name: outbound-primary
    value: '+15551234567'
    direction: INCOMING_AND_OUTGOING

Persona

The simulated caller. Self-contained (references nothing).

kind: persona
name: frustrated-caller
displayName: Dana Whitfield
language: EN
accent: US
gender: FEMALE
baseEmotion: FRUSTRATED
backstoryPrompt: file://prompts/frustrated-caller.md

Flow (improv)

An improvised simulation with a happy path and edge-case variants. References agents, a persona, and an environment by name.

kind: flow
type: improv
name: frustrated-rebooking
agents: [frontdesk]
happyPath:
  persona: frustrated-caller
  environment: default
  prompt: You call to rebook the cleaning that was cancelled on you.
edgeCases:
  - name: escalates-to-manager
    prompt: file://prompts/escalates-to-manager.md
    expectations:
      - Agent offers to escalate rather than arguing

Flow (scripted)

A step-by-step conversation graph (branches, merges, DTMF, voicemail, scenario links). Each apply replaces the whole graph.

kind: flow
type: scripted
name: booking-scripted
agents: [frontdesk]
branchingMode: ADAPTIVE
graph:
  - ref: greeting
    type: AGENT_TURN
    content: Thanks for calling, how can I help?
    steps:
      - ref: request
        type: CUSTOMER_TURN
        content: I'd like to book a cleaning.

Collector

Decides which metrics get collected on which conversations (the config form of a collector).

kind: collector
name: consent-on-frontdesk
modality: call
status: ACTIVE
metrics:
  - consent_collection_consent_obtained
  - interruption_appropriateness_appropriate
filters:
  - conditions:
      - type: AGENT
        key: frontdesk
        operator: EQUALS

Metrics are referenced by their stable slug, not a UUID, and must be visible to the project and support the collector’s modality.
Filters are condition groups: groups OR together, conditions within a group AND. An AGENT condition’s key is a config-managed agent name (resolved on apply); every other type uses its key/value verbatim.

For the full field reference of every kind, see the Config DSL reference schema.

Deploying

Bundle your resources into a single JSON body and submit it. The body is { "resources": [...], "prune": true }, where each entry is one resource in the same shape as its YAML.

Preview the changes

curl -X POST https://api.roark.ai/v1/config/plan \
  -H "Authorization: Bearer $ROARK_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @bundle.json

The response lists each planned change with an op of create, update, or delete, plus a summary:

{
  "data": {
    "changes": [
      { "configKey": "collector/consent-on-frontdesk", "kind": "collector", "name": "consent-on-frontdesk", "op": "create" }
    ],
    "summary": { "create": 1, "update": 0, "delete": 0, "noop": 0 }
  }
}

Apply

Once the plan looks right, run the same body against apply:

curl -X POST https://api.roark.ai/v1/config/apply \
  -H "Authorization: Bearer $ROARK_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @bundle.json

Each change comes back with a status (applied or failed) and, on success, the resource id.

These endpoints are available in the Node.js and Python SDKs as config.plan and config.apply, taking the same bundle.

Apply semantics

Identity is by name. Re-submitting an unchanged resource updates it in place; it never creates a duplicate. Renaming a resource is a delete of the old name plus a create of the new one.
Cross-references resolve by name within the same submission (a flow’s agents:/persona:, a collector’s AGENT filter). The referenced resource must be in the bundle or already config-managed in the project.
Prune deletes what you removed. By default, config-managed resources absent from the submission are deleted so the project matches your repo exactly. To layer additive changes without deleting, send "prune": false.
Prompts are code. Any prompt field takes an inline string or file://relative/path.md, resolved relative to your config root and inlined before you submit.
Idempotent. Applying the same bundle twice converges to the same state.

With prune enabled (the default), a resource you delete from your repo is deleted from Roark on the next apply. Submit the full desired set every time, or use "prune": false for additive-only applies.

Config-managed resources in the UI

A resource created by config is read-only in the dashboard and carries a “managed by config” badge. To change it, edit your config and re-apply. If you need to hand a resource back to manual UI editing, detach it (from the resource’s menu in the dashboard). Detaching clears its config ownership:

A later apply that still lists it will re-adopt it.
A later apply that omits it will simply leave it alone (it is no longer config-managed, so prune won’t touch it).

Recommended workflow

Keep your roark/ config in a git repo, reviewed via pull requests.
In CI, run plan on every PR and post the diff for review.
On merge to your main branch, run apply.

This gives you versioned, reviewable, reproducible Roark resources with a full audit trail in git.

Getting Started

Observability

Metrics

Simulations

Recipes

Integrations

SDKs & Libraries

Resources

Config as Code

Overview

How it works

Prerequisites

Repository layout

Resource kinds

Agent

Persona

Flow (improv)

Flow (scripted)

Collector

Deploying

Apply semantics

Config-managed resources in the UI

Recommended workflow

​Overview

​How it works

​Prerequisites

​Repository layout

​Resource kinds

​Agent

​Persona

​Flow (improv)

​Flow (scripted)

​Collector

​Deploying

​Apply semantics

​Config-managed resources in the UI

​Recommended workflow

Overview

How it works

Prerequisites

Repository layout

Resource kinds

Agent

Persona

Flow (improv)

Flow (scripted)

Collector

Deploying

Apply semantics

Config-managed resources in the UI

Recommended workflow