API Reference
API Reference

Create Experiment

Create a new experiment.

POST/api/v1/experiments/

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

This endpoint has no declared parameters.

Request body

application/json

body ExperimentCreateRequest required
4 fields
namestringrequired

The name of the experiment

descriptionstring | nulloptional

The hypothesis under test

variantsDaoExperimentVariantWrite[]optional

The variants of the experiment, as a complete set. Two or more, each on a different agent, exactly one of them the control.

Item schema
itemsDaoExperimentVariantWriterequired

One variant of an experiment as it is written.

Variants are always written as a complete set, because a weight only means anything next to the other weights, so there is no model for writing one on its own. The fields are checked by ExperimentsDao._validate_variants and not by the model, so that every rule about a variant reads in one place.

4 fields
namestringrequired

The name of the variant, unique within the experiment

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_controlbooleanoptional

Whether this is the reference variant the others are measured against

Default false
agent_idintegerrequired

The agent this variant runs

target_idintegerrequired

The channel target being split

Request example
{
  "name": "string",
  "description": "string",
  "variants": [
    {
      "name": "string",
      "weight": 0,
      "is_control": false,
      "agent_id": 0
    }
  ],
  "target_id": 0
}

Responses

200Successful Response

application/json

response ExperimentResponse required
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

Response example
{
  "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"
}
400Bad Request

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