Is the variant one subject is bucketed into, and the payload that variant…
Is the variant one subject is bucketed into, and the payload that variant carries.
GET /v1/experiment/{id}/assign
| Address | https://api.hanzo.ai/v1/experiment/{id}/assign |
| Method | GET |
| Operation | get_experiment_by_id_assign |
| Auth | Authorization: Bearer $HANZO_API_KEY |
Is the variant one subject is bucketed into, and the payload that variant carries.
The bucketing is a deterministic hash of the subject, so the same subject gets the same arm on every call for as long as the flag definition is unchanged — and this is a pure READ: it records nothing. In particular it does NOT record an exposure. The caller's SDK must emit the experiment's exposure event itself, or the analysis has an empty denominator and every arm measures zero.
An empty variant with on false is not an error — it means the flag returned nothing for this subject, so the subject is not enrolled. A flags engine that is unavailable refuses rather than defaulting to an arm. Requires a validated principal, and the experiment must exist in the caller's org and project.
Request
3 fields.
| Field | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | ID is the experiment the URL names. |
subject | query | string | yes | Subject is the unit to bucket — a user, org, session or audience key, matching the experiment's subjectKind. |
props | query | string | — | Props is a JSON object of person properties for targeting. |
Response
| Status | Body | Meaning |
|---|---|---|
200 | assignment | ok |
200 body — 5 fields.
| Field | In | Type | Always | Description |
|---|---|---|---|---|
experiment | body | string | — | Trial is the experiment that was evaluated. |
on | body | boolean | — | On is false when the flag returned nothing for this subject, which means the subject is not enrolled — not an error. |
payload | body | any | — | Payload is the opaque JSON the winning arm carries, which the caller interprets: a feature config, an ad-creative id, a subject line, a model id. |
subject | body | string | — | Subject is the unit that was bucketed. |
variant | body | string | — | Arm is the arm the subject falls in, empty when the flag enrolled it in none. |
Failure carries the platform error shape — see Errors.
Examples
hanzo experiments assign <id> --subject <subject>import { Configuration, ExperimentApi } from 'hanzoai';
const api = new ExperimentApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getExperimentByIdAssign({ id: 'id', subject: 'subject' });from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import ExperimentApi
client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = ExperimentApi(client).get_experiment_by_id_assign(id='id', subject='subject')cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)
resp, _, err := client.ExperimentAPI.GetExperimentByIdAssign(context.Background()).Execute()
if err != nil {
return err
}use hanzo_cloud::apis::{configuration::Configuration, experiment_api};
let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();
let result = experiment_api::get_experiment_by_id_assign(&cfg, Default::default()).await?;import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.ExperimentApi;
ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));
var result = new ExperimentApi(client).getExperimentByIdAssign();The method above is the one at the current release of the document. [email protected] (npm) and [email protected] (PyPI) were generated from an earlier release, where this operation carried a different id, so it spells the method differently — regenerating the clients is what makes the two agree. SDKs →
curl https://api.hanzo.ai/v1/experiment/<id>/assign?subject=%3Csubject%3E \
-H "Authorization: Bearer $HANZO_API_KEY"The door reaches experiment through the experiments tool, which names its 7 operations with its own verbs — this one among them, under a name only the door declares. describe explains any of them:
curl -X POST https://api.hanzo.ai/v1/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "describe",
"arguments": {
"op": "list_experiments"
}
}
}'How is this guide?