Create Experiment

Create an A/B experiment on a campaign.

POST/api/v1/marketing/dispatch

Request

curl -X POST "<BASE_URL>/api/v1/marketing/dispatch" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "X-CQRS-Action: CREATE_EXPERIMENT" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "name": "string",
    "tenant_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "variants": [
      {
        "kind": "CONTROL",
        "name": "string",
        "traffic_allocation_pct": 1
      }
    ]
  }'

Authorization

Minimum role: ManagerThe caller must hold this role or a higher one.
Action: CREATE_EXPERIMENT

Headers

AuthorizationstringRequired
Access token of the signed-in user, as a Bearer token. It identifies the user, their role and the workspace.
X-CQRS-ActionstringRequired
Names the command to run. Must be CREATE_EXPERIMENT for this endpoint.
Content-TypestringRequired
Always application/json.
X-Idempotency-KeystringOptional
A key you choose that is unique to this attempt. A command repeated with the same key is not applied a second time.
X-Correlation-IdstringOptional
Your own identifier for the request. Returned in the x-correlation-id response header; generated when you leave it out.

Request body

campaign_iduuidRequired
No description yet.
namestringRequired
No description yet.
minimum length 1
tenant_iduuidRequired
No description yet.
variantsarray of objectRequired
2+ variants; allocations sum to 100.
4 child fields
- kindenumRequired
  Which arm of the experiment a variant represents.
  Allowed values
  CONTROL
  TREATMENT
- namestringRequired
  No description yet.
  minimum length 1
- traffic_allocation_pctintegerRequired
  Integer percentage 0..=100. Across the variants of one experiment, this MUST sum to 100. Validated in execute_create_experiment.
- contentobject or nullOptional
  What's being tested. Optional individual fields keep the wire shape flexible — email A/B tests use headline+body, ad A/B tests use headline+image_url, SMS uses just body, etc. The narrator's "winning headline" answer reads these.
  5 child fields
  bodystring or nullOptional
  No description yet.
  ctaTextstring or nullOptional
  No description yet.
  headlinestring or nullOptional
  No description yet.
  imageUrlstring or nullOptional
  No description yet.
  templateIduuid or nullOptional
  No description yet.
alphanumber or nullOptional
No description yet.
min_detectable_effectnumber or nullOptional
0..1, absolute lift in primary_metric units. Hidden under the Advanced toggle like statistical_test/power/alpha, so it's Optional with the same unwrap_or default pattern — the collapsed-Advanced flow omits it.
powernumber or nullOptional
No description yet.
primary_metricstringOptional
No description yet.
statistical_testenum or nullOptional
No description yet.
Allowed values
- WELCH
- BAYESIAN
- CHI_SQUARED

Response

Status 202. The command was applied. The body reports the outcome and, where the command changes a record, that record's new state.

successbooleanRequired
true when the command was applied.
error_messagestringRequired
Empty when the command was applied.
projected_stateobjectOptional
The record as it stands after the command.
event_payloadobjectOptional
The event the command recorded.
insightsarray of objectOptional
Advisory notes about the result. Each has a code, a message and an impact number.

Errors

Every error carries an HTTP status. Where it also carries a code, branch on the code, not on the message.

400X-CQRS-Action is missing or names a command this route does not accept. Send CREATE_EXPERIMENT.
400DOMAIN_ROUTINGThe body is not a valid command. Check the required fields and their types.
401The access token is missing, expired or not valid.
401L1_AUTHThe caller's role is below manager or the caller has no access to this record.
403L1_POLICYA business rule refused the command. The message names the rule.
409L1_IDEMPOTENCYA command with this idempotency key was already applied.
409CONFLICTThe command would duplicate a record that must be unique.
500L3_COMMITThe command was valid but could not be saved.