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 percentage of the channel target's traffic this variant answers. The weights of an experiment's variants must add up to 100. (E.g., two variants with a weight of 50 each split the traffic evenly.)

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"
    }
  ]
}