{ "openapi": "3.0.0", "info": { "title": "abEx - A/B Experiment API", "version": "1.0.0", "description": "Facilitates running A/B experiments. Simple, fast, and reliable." }, "paths": { "/v1/create": { "post": { "summary": "Creates a new experiment and provides a unique experimentId", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "experimentName": { "type": "string", "description": "Name of your experiment" } }, "required": ["experimentName"], "example": { "experimentName": "MyFirstExperiment" } } } } }, "responses": { "200": { "description": "IMPORTANT: make sure you save the value returned in the experimentId field. This is a required parameter, in combination with your experiment name, for all other endpoints and this is the only time the API will provide this ID to you. If you lose this you will be unable to further interact with your experiment.", "content": { "application/json": { "examples": { "MyFirstExperiment": { "value": { "status": "success", "experimentInfo": { "experimentName": "MyFirstExperiment", "experimentId": 17945202, "createdAt": "2024-02-19T10:17:40.994Z", "experimentStatus": "Not started" } } } } } } }, "422": { "description": "One or more of the supplied fields contain incorrect or invalid values." } } } }, "/v1/rename": { "post": { "summary": "Renames an experiment", "requestBody": { "description": "Changes the experimentName value to a new one while keeping the same experimentId. Experiment name cannot be changed while the experiment is running.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "experimentName": { "type": "string", "description": "Name of the experiment you wish to rename" }, "experimentId": { "type": "integer", "description": "ID of the experiment, provided during creation using /create endpoint" }, "newName": { "type": "string", "description": "New name for the experiment" } }, "required": ["experimentName", "experimentId", "newName"], "example": { "experimentName": "MyFirstExperiment", "experimentId": 17945202, "newName": "MySecondExperiment" } } } } }, "responses": { "200": { "description": "Rename MyFirstExperiment to MySecondExperiment", "content": { "application/json": { "examples": { "MyFirstExperiment": { "value": { "status": "success", "experimentInfo": { "experimentName": "MySecondExperiment", "experimentId": 17945202, "createdAt": "2024-02-24T13:14:42.043Z", "experimentStatus": "Not started" } } } } } } }, "422": { "description": "One or more of the supplied fields contain incorrect or invalid values." } } } }, "/v1/start": { "post": { "summary": "Starts an experiment", "requestBody": { "description": "Optional params will default as follows:

If both sampleSize and durationDays are not provided, the experiment will default to run for 14 days with no limit to sample size
If only durationDays is provided, there will be no limit to sampleSize
If only sampleSize is provided, there is no end date set. However, the system will force an experiment to stop if it has been running longer than 6 months.
Traffic rate will default to 100 if not supplied

", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "experimentName": { "type": "string", "description": "Name of the experiment you wish to start" }, "experimentId": { "type": "integer", "description": "ID of the experiment, provided during creation using /create endpoint" }, "durationDays": { "type": "integer", "description": "Duration in days you wish to run the experiment. Experiment will automatically stop exactly that many days after starting (i.e. if you start at 11:59pm on January 1 and run for 2 days, it will stop at 11:59pm on January 3)" }, "sampleSize": { "type": "integer", "description": "Total number of allocations to either the A or B side of your experiment you wish to capture before the experiment stops. Experiment will stop automatically once this number has been reached (sum of allocations to A + B)" }, "trafficRate": { "type": "integer", "description": "Defaults to 100. Defines the % of users who are allocated to either A or B / unallocated users. For example, if you set the traffic rate to 50, this means that 50% of the total users will be allocated to either A or B, while the remaining 50% will be unallocated (variant \"U\")." } }, "required": ["experimentName", "experimentId"], "example": { "experimentName": "MyFirstExperiment", "experimentId": 17945202, "durationDays": 30, "trafficRate": 100 } } } } }, "responses": { "200": { "description": "Start MyFirstExperiment", "content": { "application/json": { "examples": { "MyFirstExperiment": { "value": { "status": "success", "experimentInfo": { "experimentName": "MyFirstExperiment", "experimentId": 17945202, "createdAt": "2024-02-19T10:17:40.994Z", "experimentStatus": "Running", "runData": { "startDate": "2024-02-19T10:42:33.066Z", "durationDays": 30, "endDate": "2024-03-20T10:42:33.066Z", "trafficRate": 100 } } } } } } } }, "422": { "description": "One or more of the supplied fields contain incorrect or invalid values." } } } }, "/v1/status": { "get": { "summary": "Gets various information about an experiment, including allocation counts if available", "parameters": [ { "in": "query", "name": "experimentName", "schema": { "type": "string" }, "required": true, "description": "Name of the experiment" }, { "in": "query", "name": "experimentId", "schema": { "type": "integer" }, "required": true, "description": "ID of the experiment, provided during creation using /create endpoint" } ], "responses": { "200": { "description": "Response object fields may vary depending on the status of the experiment. See examples for variations.", "content": { "application/json": { "examples": { "MyFirstExperiment Ended": { "value": { "status": "success", "experimentInfo": { "experimentName": "MyFirstExperiment", "experimentId": 17945202, "createdAt": "2024-02-24T13:14:42.043Z", "experimentStatus": "Flat B", "runData": { "startDate": "2024-02-24T13:30:32.304Z", "durationDays": 30, "endDate": "2024-02-25T07:51:07.566Z", "finalDurationDays": 1, "finalSampleSize": 8, "trafficRate": 100, "allocatedUsers": { "A": 5, "B": 3 } } } } }, "MyFirstExperiment Running": { "value": { "status": "success", "experimentInfo": { "experimentName": "MyFirstExperiment", "experimentId": 17945202, "createdAt": "2024-02-19T10:17:40.994Z", "experimentStatus": "Running", "runData": { "startDate": "2024-02-19T10:42:33.066Z", "durationDays": 30, "endDate": "2024-03-20T10:42:33.066Z", "trafficRate": 100, "allocatedUsers": { "A": 5, "B": 3 } } } } }, "MyFirstExperiment Not Started": { "value": { "status": "success", "experimentInfo": { "status": "success", "experimentInfo": { "experimentName": "MySecondExperiment", "experimentId": 90670854, "createdAt": "2024-02-25T08:25:01.911Z", "experimentStatus": "Not started" } } } } } } } }, "422": { "description": "One or more of the supplied fields contain incorrect or invalid values." } } } }, "/v1/allocation": { "post": { "summary": "Get the variant of specified user. If user does not yet have a variant, one will be assigned at the time of calling this endpoint.", "requestBody": { "description": "Calling this endpoint will allocate a user. Once a user is allocated, calling this endpoint for the same user will always give the same variant (unless the experiment is stopped or restarted).
Regardless of the experiment status, or even if the experiment exists, this endpoint will never fail and will instead return variant \"U\" in these scenarios", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "experimentName": { "type": "string", "description": "Name of the experiment" }, "experimentId": { "type": "integer", "description": "ID of the experiment, provided during creation using /create endpoint" }, "userId": { "type": "string", "description": "Unique ID of the user you wish to allocate" } }, "required": ["experimentName", "experimentId", "userId"], "example": { "experimentName": "MyFirstExperiment", "experimentId": 17945202, "userId": "user1" } } } } }, "responses": { "200": { "description": "Allocate user1 in MyFirstExperiment", "content": { "application/json": { "examples": { "MyFirstExperiment": { "value": { "status": "success", "experimentInfo": { "experimentName": "MyFirstExperiment", "experimentId": 17945202, "userId": "user1", "variant": "A" } } } } } } }, "422": { "description": "One or more of the supplied fields contain incorrect or invalid values." } } } }, "/v1/restart": { "post": { "summary": "Restarts an experiment", "requestBody": { "description": "Identical to /start endpoint, but can be called for a running or already ended experiment. NOTE: Restarting an experiment will reset all existing allocations.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "experimentName": { "type": "string", "description": "Name of the experiment you wish to restart" }, "experimentId": { "type": "string", "description": "ID of the experiment, provided during creation using /create endpoint" }, "durationDays": { "type": "integer", "description": "Duration in days you wish to run the experiment. Experiment will automatically stop exactly that many days after starting (i.e. if you start at 11:59pm on January 1 and run for 2 days, it will stop at 11:59pm on January 3)" }, "sampleSize": { "type": "integer", "description": "Total number of allocations to either the A or B side of your experiment you wish to capture before the experiment stops. Experiment will stop automatically once this number has been reached (sum of allocations to A + B)" }, "trafficRate": { "type": "integer", "description": "Defaults to 100. Defines the % of users who are allocated to either A or B / unallocated users. For example, if you set the traffic rate to 50, this means that 50% of the total users will be allocated to either A or B, while the remaining 50% will be unallocated (variant \"U\")." } }, "required": ["experimentName", "experimentId"], "example": { "experimentName": "MyFirstExperiment", "experimentId": 17945202, "durationDays": 30, "trafficRate": 100 } } } } }, "responses": { "200": { "description": "Restart MyFirstExperiment", "content": { "application/json": { "examples": { "MyFirstExperiment": { "value": { "status": "success", "experimentInfo": { "experimentName": "MyFirstExperiment", "experimentId": 17945202, "createdAt": "2024-02-19T10:17:40.994Z", "experimentStatus": "Running", "runData": { "startDate": "2024-02-19T10:42:33.066Z", "durationDays": 30, "endDate": "2024-03-20T10:42:33.066Z", "trafficRate": 100 } } } } } } } }, "422": { "description": "One or more of the supplied fields contain incorrect or invalid values." } } } }, "/v1/stop": { "post": { "summary": "Stops an experiment, forcing all users to a specified variant", "requestBody": { "description": "Stops a running experiment. Cannot be executed for an experiment that is not running.
By default, the experiment will change to \"Stopped\" status unless otherwise specified in the decision field. See /decision endpoint for more information.
", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "experimentName": { "type": "string", "description": "Name of the experiment you wish to stop" }, "experimentId": { "type": "integer", "description": "ID of the experiment, provided during creation using /create endpoint" }, "decision": { "type": "string", "description": "Sets behavior of /allocation endpoint for users. See /decision endpoint for more information" } }, "required": ["experimentName", "experimentId"], "example": { "experimentName": "MyFirstExperiment", "experimentId": 17945202 } } } } }, "responses": { "200": { "description": "Stop MyFirstExperiment", "content": { "application/json": { "examples": { "MyFirstExperiment": { "value": { "status": "success", "experimentInfo": { "experimentName": "MyFirstExperiment", "experimentId": 17945202, "createdAt": "2024-02-24T13:14:42.043Z", "experimentStatus": "Stopped", "runData": { "startDate": "2024-02-24T13:30:32.304Z", "durationDays": 30, "endDate": "2024-02-25T07:51:07.566Z", "finalDurationDays": 1, "trafficRate": 100, "allocatedUsers": { "A": 5, "B": 3 } } } } } } } } }, "422": { "description": "One or more of the supplied fields contain incorrect or invalid values." } } } }, "/v1/decision": { "post": { "summary": "Provides/updates decision of an experiment", "requestBody": { "description": "IMPORTANT: Once a decision is made, previously stored variants for users of the experiments will be cleared and you can not change the experiment back to \"Stopped\" status.

May only be called after an experiment has ceased running (using /stop endpoint). Previous decisions can be overwritten. An experiment decision dictates how the /allocation endpoint behaves for users as follows:

Decision Input	New experiment status	Effect
A	Flat A	All users receive variant A
B	Flat B	All users receive variant B
U	U	All users receive variant U