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

Required by the API: submit the complete variant set with at least two variants, each using a different agent. Exactly one must be the control, every weight must be a positive whole number, and all weights must total 100.

Item schema
itemsDaoExperimentVariantWriterequired

One variant in an experiment. Submit variants as a complete set with at least two different agents, exactly one control, and positive whole-number percentage weights totaling 100.

4 fields
namestringrequired

The name of the variant, unique within the experiment

weightintegerrequired

The positive whole-number percentage of the channel target's traffic this variant answers. The complete set of variant weights must total 100.

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 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

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.

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