Skip to content
Navigation

Get or create a CMAB assignment for a participant

POST
https://api.evidential.dev/v1/experiments/{experiment_id}/assignments/{participant_id}/assign_cmab

Gets or creates an arm assignment for a participant. Used only for CMAB experiments. If an assignment already exists, context_inputs in the request body may be null. If you provide it anyway, it is ignored.

Authorization

  • DatasourceApiKey
    API key in header
    required

    X-API-Key: <token>

Path parameters

  • participant_id
    string
    required

    Your application's identifier for the participant.

  • experiment_id
    string
    required

    The ID of the experiment to fetch.

Query parameters

  • create_if_none
    optional
    boolean

    Create an assignment if none exists. Set to false to check for an existing assignment without creating one.

    default: true

Request body JSON required

  • context_inputs
    required

    The context values for the assignment, one for each context defined on the experiment. Values are matched to contexts by context_id, not by position in the list. May be null when you retrieve an existing assignment. Otherwise, valid inputs are required.

    Any of the following:

    • array<unknown>
      • context_id
        string
        required

        Unique identifier for the context.

      • context_value
        number
        required

        Value of the context.

    • null
  • type
    optional
    string
    default: "cmab_assignment"

Returns

200

Successful Response

JSON
  • experiment_id
    string
    required
  • participant_id
    string
    required
  • assignment
    required

    Null if no assignment. Strata are not included.

    Any of the following:

    • Assignment
      • arm_id
        string
        required

        ID of the arm this participant was assigned to. Same as Arm.arm_id.

      • participant_id
        string
        required

        Unique identifier for the participant. This is the primary key for the participant in the data warehouse.

        maxLength: 64
      • arm_name
        string
        required

        The arm this participant was assigned to. Same as Arm.arm_name.

        maxLength: 100
      • cluster_key
        optional

        Cluster identifier for this participant. Present for cluster-randomized preassigned experiments.

        Any of the following:

        • string
        • null
      • created_at
        optional

        The date and time the assignment was created.

        Any of the following:

        • string
        • null
      • strata
        optional

        List of properties and their values for this participant used for stratification or tracking metrics. If stratification is not used, this will be None.

        Any of the following:

        • array<unknown>
          • field_name
            string
            required
            maxLength: 300 · minLength: 1
          • strata_value
            optional

            Any of the following:

            • string
            • null
        • null
      • observed_at
        optional

        The date and time the outcome was recorded.

        Any of the following:

        • string
        • null
      • outcome
        optional

        The observed outcome for this assignment.

        Any of the following:

        • number
        • null
      • autofailed_outcome
        optional

        Whether Evidential failed this outcome automatically (true) or a real outcome was observed (false). Null if no outcome was recorded.

        Any of the following:

        • boolean
        • null
      • context_values
        optional

        List of context values for this assignment. If no contexts are used, this will be None.

        Any of the following:

        • array<number>
        • null
    • null

400

The request is invalid. Check that the request body matches the required structure and that all required fields and headers are present.

403

You did not provide a valid API key, or your API key does not have permission for this operation.

Tip: Check that the API key in the X-API-Key header has access to the data source or experiment.

404

The resource was not found, or you do not have access to it.

Tip: Check that the API key in the X-API-Key header has access to the data source or experiment.

422

Validation Error
JSON
  • detail
    optional
    array of
    object
    • loc
      array of
      required

      Any of the following:

      • string
      • integer
    • msg
      string
      required
    • type
      string
      required
    • input
      optional
      unknown
    • ctx
      optional
      object

Type to search…

↑↓ navigate↵ selectEsc close