Experiments

9 operations. {prefix} is the route prefix passed to MapAgentPrism; the template uses /agentprism.

GET {prefix}/api/experiments

Operation ID: AgentPrismListExperiments

Lists a tenant’s A/B experiments.

Experiments in every state are returned — Draft, Running, and Stopped — because a stopped experiment is still the record its results are read from. At most one of them per agent can be Running. The entries carry the variant weights, so a client can show the traffic split without a second call.

Authorization: bearer authentication; Reader role policy when that policy is registered; ExperimentsRead API-key scope.

Response	Body	Headers
200 OK	application/json → array of Experiment	—

GET {prefix}/api/experiments/{name}

Operation ID: AgentPrismGetExperiment

Gets a single A/B experiment.

The response is the experiment’s definition — arms, weights, status — not its outcome; read the per-arm counts from the results endpoint and the canary rule from the canary endpoint. Experiments are scoped to the calling tenant, and a name that belongs to another tenant is reported as 404.

Authorization: bearer authentication; Reader role policy when that policy is registered; ExperimentsRead API-key scope.

Parameter	In	Required	Type	Description and rules
name	path	yes	string	—

Response	Body	Headers
200 OK	application/json → Experiment	—

PUT {prefix}/api/experiments/{name}

Operation ID: AgentPrismSaveExperiment

Creates or updates an experiment.

An experiment can only be set up between versions of the same agent; code-sourced agents have no version history, so they are rejected. Variant weights must sum to 100.

Authorization: bearer authentication; Admin role policy when that policy is registered; ExperimentsAdmin API-key scope.

Parameter	In	Required	Type	Description and rules
name	path	yes	string	—

Request body (required):

• application/json → ExperimentSaveRequest

Response	Body	Headers
200 OK	application/json → Experiment	—

DELETE {prefix}/api/experiments/{name}

Operation ID: AgentPrismDeleteExperiment

Deletes an experiment. A running experiment must be stopped first.

Deleting a Running experiment returns 409; stop it first, so traffic is never left splitting against a definition that no longer exists. Runs already assigned to an arm keep their assignment and stay readable, but the per-arm results endpoint disappears with the experiment — export the results before deleting. An unknown name returns 404.

Authorization: bearer authentication; Admin role policy when that policy is registered; ExperimentsAdmin API-key scope.

Parameter	In	Required	Type	Description and rules
name	path	yes	string	—

Response	Body	Headers
204 No Content	—	—

GET {prefix}/api/experiments/{name}/canary

Operation ID: AgentPrismGetExperimentCanary

Gets the canary rule and its current evaluation.

The evaluation is not persisted; it is recalculated on every call using current run results.

Authorization: bearer authentication; Reader role policy when that policy is registered; ExperimentsRead API-key scope.

Parameter	In	Required	Type	Description and rules
name	path	yes	string	—

Response	Body	Headers
200 OK	application/json → ExperimentCanaryResponse	—

PUT {prefix}/api/experiments/{name}/canary

Operation ID: AgentPrismSetExperimentCanary

Defines or removes the canary rule (a ‘null’ body removes it).

Can only be defined on two-arm experiments: canaryVariant is the canary, and the single remaining arm counts as control. Works regardless of the experiment’s status (Draft or Running).

Authorization: bearer authentication; Admin role policy when that policy is registered; ExperimentsAdmin API-key scope.

Parameter	In	Required	Type	Description and rules
name	path	yes	string	—

Request body (optional):

• application/json → CanaryPolicy

Response	Body	Headers
200 OK	application/json → Experiment	—

GET {prefix}/api/experiments/{name}/results

Operation ID: AgentPrismGetExperimentResults

Gets a per-arm summary of count, error rate, tokens, and duration.

There is no statistical claim of a ‘winner’; raw counts are shown.

Authorization: bearer authentication; Reader role policy when that policy is registered; ExperimentsRead API-key scope.

Parameter	In	Required	Type	Description and rules
name	path	yes	string	—

Response	Body	Headers
200 OK	application/json → ExperimentResultsResponse	—

POST {prefix}/api/experiments/{name}/start

Operation ID: AgentPrismStartExperiment

Starts the experiment; traffic begins splitting according to the weights.

Only one experiment can run for the same agent at a time.

Authorization: bearer authentication; Admin role policy when that policy is registered; ExperimentsAdmin API-key scope.

Parameter	In	Required	Type	Description and rules
name	path	yes	string	—

Response	Body	Headers
200 OK	application/json → Experiment	—

POST {prefix}/api/experiments/{name}/stop

Operation ID: AgentPrismStopExperiment

Stops the experiment; new runs go to the current version.

Stopping affects only new runs: a run already in flight keeps the arm it was assigned, and the recorded results stay intact and readable afterwards. Stopping an experiment that is not Running returns 409, and so does an unknown name — this endpoint does not distinguish the two. Once stopped, the agent’s own current version serves all traffic again, and the same agent becomes free for another experiment.

Authorization: bearer authentication; Admin role policy when that policy is registered; ExperimentsAdmin API-key scope.

Parameter	In	Required	Type	Description and rules
name	path	yes	string	—

Response	Body	Headers
200 OK	application/json → Experiment	—