ROroarkhq
Autoimprove

Start an Autoimprove job

Changed on

Commission Roark on an objective. It clones the agent into a staging shadow (or uses your designated staging agent), authors a validation suite of simulated callers, measures a baseline, changes the staging configuration, and re-tests until the objective metric passes its target. Production is never touched by the loop; verified changes wait for promotion.

Requires an active provider integration (Vapi, Retell, or ElevenLabs) with agent config writes enabled. One live job per agent: starting a second returns a conflict.

The job runs asynchronously; poll GET /v1/autoimprove/job/{jobId} or watch it in the dashboard. When its status is NEEDS_INPUT, answer via the answer endpoint; when AWAITING_PROMOTE, promote or dismiss.

post/v1/autoimprove/job

Request

  • Base URL
    https://api.roark.ai
  • URL
    https://api.roark.ai/v1/autoimprove/job
  • Auth
    HTTP bearer

Request body

agentIdstring uuid required

The production agent to improve. It is never modified until you promote.

objectiveMetricDefinitionIdstring uuid required

The metric that defines success: a pass/fail metric, or a threshold variant of a scale metric (for example "PII Handling >= 4"). Roark measures the pass rate of this metric across simulated calls.

objectiveLabelstring required

Human-readable label for the objective, shown everywhere the job appears.

targetValuenumber

The pass-rate percentage that counts as fixed. Defaults to 90.

stagingAgentIdstring uuid

An existing agent to stage changes on instead of the default shadow clone. Must be a different agent from agentId, on the same provider.

customerIntegrationIdstring uuid

The provider integration whose credentials Roark uses. Omit to use the project's active integration for the agent's provider. The integration must have agent config writes enabled.

validationRunPlanIdstring uuid

An existing simulation run plan to validate with. Omit to let Roark author its own suite.

maxIterationsinteger

Cap on decision turns. Defaults to 50.

maxSimCallsinteger

Cap on simulated calls dialed. Defaults to 200.

Example request

{
  "agentId": "b3b0c8e2-4c1d-4f6a-9e2b-1a2b3c4d5e6f",
  "objectiveMetricDefinitionId": "f2f0c8e2-4c1d-4f6a-9e2b-1a2b3c4d5e6f",
  "objectiveLabel": "Consent collection should pass",
  "targetValue": 90
}

Response

The job was created and its loop started.

Changes

  • 29256c5296cfRevision changes
    • breaking

      the response property / became nullable for the status

    • warning

      added the new CHANNEL enum value to the / response property for the response status

  • 99617fc5ccabRevision changes
    • info

      endpoint added