API for creating, managing, and querying Warp cloud agent runs.
These endpoints allow users to programmatically spawn agents, list runs,
and retrieve detailed run information.
Authentication: Bearer token (Warp API key). Obtain from account settings. Pass as Authorization: Bearer YOUR_API_KEY.
POST /agent/runs/{runId}/cancel
Cancel a run
Cancel an agent run that is currently queued or in progress; once
cancelled, the run transitions to a cancelled state. Not all runs can
be cancelled: a run already in a terminal state, in PENDING, or of an
unsupported type (self-hosted, local, GitHub Action) is rejected
instead — see the error responses below for each case.
- runId (path, required): The unique identifier of the run to cancel
GET /agent/schedules/{scheduleId}
Get scheduled agent details
Retrieve detailed information about a specific scheduled agent,
including its configuration, history, and next scheduled run time.
- scheduleId (path, required): The unique identifier of the scheduled agent
PUT /agent/schedules/{scheduleId}
Update a scheduled agent
Update an existing scheduled agent's configuration.
All fields except agent_config are required.
- scheduleId (path, required): The unique identifier of the scheduled agent
DELETE /agent/schedules/{scheduleId}
Delete a scheduled agent
Delete a scheduled agent. This will stop all future scheduled runs.
- scheduleId (path, required): The unique identifier of the scheduled agent
PATCH /factory/scorers/{scorer_id}
Update a scorer's definition
Apply a partial update to a scorer's definition; omitted fields are
left unchanged, but at least one field must be provided, and the
owning factory is immutable. Each update bumps the scorer's version
without invalidating any scoring judge already in flight, since
judges validate against the definition snapshot taken at dispatch
time, and historical scores keep their recorded classification
values. Supplying `scope_mode` or `agent_uids` replaces the scorer's
scope in full.
- scorer_id (path, required): The scorer identifier
DELETE /factory/scorers/{scorer_id}
Delete a scorer
Permanently delete a scorer. This is not reversible and it is not an
archive: the scorer's scoring attempts, scores, judge reasoning, self-improvement
config, and self-improvement triage results go with it, and the scorer stops
being readable through this API as soon as the call returns.
The underlying rows and the judge-reasoning blobs stored outside the
database are destroyed shortly afterwards by the deletion sweep, which
removes each blob before the record that references it and retries until
both are gone.
- scorer_id (path, required): The scorer identifier
POST /factory/scorers
Create a scorer
Create an active run scorer for a factory with either selected-agent or
all-agent scope. Creating a scorer does not start scoring. Pass
self_improvement_enabled to also turn on self-improvement for the new scorer in the same
request; the scorer and its self-improvement config are created atomically, so
a failure leaves neither behind.
GET /factory/scorers
List agent scorers
List the scorers owned by the caller's team, including scope agents
and aggregate scoring stats. Pass factory_uid to narrow the result to a
single factory.
GET /factory/scorers/{scorer_id}/metrics/pass-rate
Get a scorer's pass-rate metric over a date range
Returns a period-aligned pass-rate series plus a full-range aggregate
for the scorer's dashboard chart, computed directly from every live
score in [start_date, end_date) rather than the capped,
unfiltered recent-attempts list /results returns. The headline
pass_rate and the series describe the same window and denominator, so
they cannot disagree. Binning follows the same day/week/month rules
and 365-period cap as GET /factory/{uid}/metrics.
- scorer_id (path, required): The scorer identifier
- start_date (query): RFC3339 UTC range start, inclusive. Defaults to 30 days before end_date.
- end_date (query): RFC3339 UTC range end, exclusive. Defaults to now.
- group_by_period (query): Binning granularity for the series. Defaults to day.
GET /factory/scorers/{scorer_id}/self-improvement-config
Get a scorer's self-improvement config
Retrieve the self-improvement configuration for a scorer: whether self-improvement is
enabled for it.
- scorer_id (path, required): The scorer identifier
PUT /factory/scorers/{scorer_id}/self-improvement-config
Enable self-improvement for a scorer
Turn self-improvement on for a scorer, marking its config active. Self-improvement acts
on runs the scorer itself already scores as failing (scored label's
score below the scorer's threshold); this endpoint carries no
classification data of its own.
- scorer_id (path, required): The scorer identifier
DELETE /factory/scorers/{scorer_id}/self-improvement-config
Disable self-improvement for a scorer
Turn self-improvement off for a scorer by removing its config.
- scorer_id (path, required): The scorer identifier
POST /factory/run-scoring/dispatches
Manually dispatch scoring for one or more runs
Immediately dispatch judge runs for the named (run, scorer) pairs,
bypassing the two-hour idle cool-down, automatic sampling, and the
scorer-created-after-run gate, since the caller selected the exact
run — even a 0% sampling rate still accepts a manual dispatch. The
full target set is validated before dispatch begins, and each pair's
outcome (dispatched, already in flight, or failed) is reported
independently.