Replace defs

Creates or replaces the flag definition at the path's key and returns the stored row.

PUT /v1/flag/defs/{key}

Flag → · All API references → · Get started →

Address	`https://api.hanzo.ai/v1/flag/defs/{key}`
Method	`PUT`
Operation	`put_flag_defs_by_key`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Creates or replaces the flag definition at the path's key and returns the stored row. The BODY IS THE DEFINITION DOCUMENT — the flag-definition JSON object the evaluator consumes — and it is stored verbatim except that its "key" is forced to the key in the URL, so a document can never be filed under a name other than the one it was addressed by. Every write bumps the version and appends to the change log under the caller's identity. A key that lets an org into a capability that is not ga — research, machines — is a SuperAdmin's to set, never an org admin's, and its write is on the audit trail before it lands; every other key is an owner's or admin's of the org, never a member's.

Request

2 fields, body application/json (required).

Field	In	Type	Required	Description
`key`	path	string	yes	Key is the flag key to write, from the path.
`(body)`	body	any	yes

Response

Status	Body	Meaning
`200`	flag.DefRow	ok
`default`	problem-details	refused

200 body — 5 fields.

Field	In	Type	Always	Description
`definition`	body	any	—	Definition is the flag-definition document the evaluator consumes, kept BYTE-FOR-BYTE as it was written.
`key`	body	string	—	Key is the flag's primary key in the caller's (org, project) store, and the name evaluation looks it up by.
`updated_at`	body	string	—	UpdatedAt is when the definition was last written, RFC 3339 UTC.
`updated_by`	body	string	—	UpdatedBy is the email of the principal who last wrote it.
`version`	body	integer (int64)	—	Version is 1 when the key was created and rises by one on every overwrite.

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo flag defs set <key>

.ts

.py

.go

.rs

.java

import { Configuration, FlagApi } from 'hanzoai';

const api = new FlagApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.putFlagDefsByKey({ key: 'key' });

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import FlagApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = FlagApi(client).put_flag_defs_by_key(key='key')

cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.FlagAPI.PutFlagDefsByKey(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_client::apis::{configuration::Configuration, flag_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = flag_api::put_flag_defs_by_key(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.FlagApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new FlagApi(client).putFlagDefsByKey();

curl -X PUT https://api.hanzo.ai/v1/flag/defs/<key> \
  -H "Authorization: Bearer $HANZO_API_KEY"

MCP reaches flag through the flag tool, which names its 8 operations with its own verbs — this one among them, under a name only MCP 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": "get_flag_activity"
         }
       }
     }'

Flag API · All Hanzo APIs · Interactive reference

Was this page useful?

PreviousCreate flag NextDelete workflows