API Reference
API Reference

Start Experiment

Start an experiment. (Only an experiment in 'draft' status can be started.)

POST/api/v1/experiments/{experiment_id}/start

Authentication

Syllable-API-Keyrequired

Send Syllable-API-Key in the header.

Need a credential? Create or manage an API token in the Syllable Console.

Parameters

Path parameters

experiment_id integer path required

Responses

200Successful Response

application/json

response ExperimentStartResponse required
2 fields
experimentExperimentResponserequired

The experiment, now running

12 fields
idintegerrequired

The internal ID of the experiment

namestringrequired

The name of the experiment

target_idinteger | nullrequired

The channel target being split, or null if that target has since been deleted. A running experiment always has one.

variantsDaoExperimentVariantDetail[]required

The variants of the experiment, in a stable order

Item schema
itemsDaoExperimentVariantDetailrequired

A variant, with the name of the agent it runs resolved for display.

6 fields
idintegerrequired

The internal ID of the variant

namestringrequired

The name of the variant, which is the grouping key in reports

weightintegerrequired

The relative weight of the variant, not a percentage. (E.g., if two variants both have a weight of 10, they are equally likely to be selected.)

is_controlbooleanrequired

Whether this is the reference variant the others are measured against

agent_idintegerrequired

The agent this variant runs

agent_namestringrequired

The name of that agent

descriptionstring | nulloptional

The hypothesis under test

statusenum<string>required

draft, running, or stopped

Allowed values ["draft","running","stopped"]
started_atstring (date-time) | nulloptional

When the experiment started

stopped_atstring (date-time) | nulloptional

When the experiment stopped

created_atstring (date-time)required

When the experiment was created

updated_atstring (date-time)required

When the experiment was last written

last_updated_bystringrequired

Who last wrote it

targetDaoExperimentTargetSummary | nulloptional

The channel target being split, resolved for display. Null when the target has since been deleted, and when the read did not load it.

5 options
idintegerrequired

The internal ID of the channel target

targetstringrequired

The target itself, such as a phone number

target_modeenum<string>required

The mode of the channel target

Allowed values ["voice","chat","sms","email","whatsapp"]
channel_idintegerrequired

The channel the target belongs to

channel_namestringrequired

The name of that channel

warningsstring[]optional

Things that weaken the result without invalidating it, such as a variant whose agent does not pin a prompt version, so that the prompt can be edited while the experiment runs

Item schema
itemsstringrequired
Response example
{
  "experiment": {
    "id": 0,
    "name": "string",
    "target_id": "string",
    "variants": [
      {
        "id": 0,
        "name": "string",
        "weight": 0,
        "is_control": true,
        "agent_id": 0,
        "agent_name": "string"
      }
    ],
    "description": "string",
    "status": "string",
    "started_at": "string",
    "stopped_at": "string",
    "created_at": "string",
    "updated_at": "string",
    "last_updated_by": "string",
    "target": "string"
  },
  "warnings": [
    "string"
  ]
}
400Bad Request

No response body is declared.

404Not Found

No response body is declared.

409Conflict

No response body is declared.

422Validation Error

application/json

response HTTPValidationError required
1 field
detailValidationError[]optional
Item schema
itemsValidationErrorrequired
3 fields
locstring | integer[]required
Item schema
itemsstring | integerrequired
2 options
Option 1stringrequired
Option 2integerrequired
msgstringrequired
typestringrequired
Response example
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}