# Create roster URL: https://docs.hanzo.ai/docs/openapi/agent/post-agent-roster > Turns an approved organization chart into agent definitions in the caller's organization, resolving manager reporting lines (`parent` and `lineage`) and shared role templates with explicit versions. `POST /v1/agent/roster` > [Agent →](https://docs.hanzo.ai/docs/openapi/agent) · [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides) | | | | ------------- | -------------------------------------- | | **Address** | `https://api.hanzo.ai/v1/agent/roster` | | **Method** | `POST` | | **Operation** | `post_agent_roster` | | **Auth** | `Authorization: Bearer $HANZO_API_KEY` | Turns an approved organization chart into agent definitions in the caller's organization, resolving manager reporting lines (`parent` and `lineage`) and shared role templates with explicit versions. Applying the same roster again (or resuming an interrupted launch) updates existing roles in place without duplicating agents or budgets. ## Request 20 fields, body `application/json` (required). | Field | In | Type | Required | Description | | ---------------------------- | ---- | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `roles` | body | agent.RoleSpec\[] | — | Roles are the explicit role definitions to create or update in topological manager order. | | `roles[].cap_micro_usd` | body | integer (int64) | — | CapMicroUSD is the period budget cap in integer micro-USD; defaults to the template's cap when omitted. | | `roles[].duties` | body | string | — | Duties is the system prompt (instructions) governing the role's behavior and output. | | `roles[].executionMode` | body | string | — | ExecutionMode is "one-shot" (default) or "long-running". | | `roles[].expertise` | body | string | — | Expertise is the catalog description explaining the role's domain expertise. | | `roles[].function` | body | string | — | Function names the studio function ("lead" or one of the seven studio functions). | | `roles[].manager` | body | string | — | Manager names the parent agent handle or id this role reports to in the org chart. | | `roles[].max_task_micro_usd` | body | integer (int64) | — | MaxTaskMicroUSD is the per-run budget ceiling in integer micro-USD; defaults to the template's ceiling when omitted. | | `roles[].model` | body | string | — | Model optionally overrides the model this role runs on. | | `roles[].name` | body | string | — | Name is the agent handle to create or update in the organization (e.g. "venture-lead" or "specialist-regulatory-clinical"). | | `roles[].output` | body | string | — | Output describes the required deliverable format for this role. | | `roles[].period` | body | string | — | Period is the budget reset window (day, week, or month); defaults to "month". | | `roles[].schedule` | body | string | — | Schedule is the 5-field cron expression when executionMode is "long-running". | | `roles[].sources` | body | string\[] | — | Sources lists the knowledge and evidence sources this role is permitted to query. | | `roles[].templateId` | body | string | — | TemplateID optionally selects a shared RoleTemplate by id to inherit defaults from. | | `roles[].templateVersion` | body | string | — | TemplateVersion records the explicit shared template version used for this role; defaults to StudioTemplateVersion. | | `roles[].tools` | body | string\[] | — | Tools lists the MCP tool names this role is allowed to call. | | `seedDefaultSeven` | body | boolean | — | SeedDefaultSeven, when true, seeds the default venture-lead and all seven studio function specialists before applying any custom roles in Roles. | | `templateVersion` | body | string | — | TemplateVersion is the shared role template version to stamp on enrolled roles; defaults to StudioTemplateVersion. | | `venture` | body | string | — | Venture is the venture slug this roster belongs to, used for attribution and metadata. | ## Response | Status | Body | Meaning | | --------- | -------------------- | ------- | | `200` | agent.applyRosterOut | ok | | `default` | problem-details | refused | `200` body — 28 fields. | Field | In | Type | Always | Description | | ----------------------------- | ---- | ------------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `agents` | body | agent.agentView\[] | — | Agents are the enrolled agent views in the organization after applying the roster. | | `agents[].avatar` | body | string | — | Avatar is an image the agent is drawn as — a link to one, or the bytes inline as a data URL, up to 96 KiB. | | `agents[].avatar_licence` | body | string | — | AvatarLicence is the short name of the licence the avatar image is used under ("Public domain", "CC0"). | | `agents[].avatar_source` | body | string | — | AvatarSource is the page the avatar image is described on, where its author and licence can be read (a Wikimedia Commons file page, say). | | `agents[].cap_micro_usd` | body | integer (int64) | — | CapMicroUSD is the total this agent may spend within one Period, as an integer number of micro-USD (1,000,000 = $1). | | `agents[].computeRef` | body | string | — | ComputeRef is the visor machine this bot is bound to, opaque here: this package stores and echoes it, and the binding's lifecycle belongs elsewhere. | | `agents[].consumed_micro_usd` | body | integer (int64) | — | ConsumedMicroUSD is what has been spent in the current period, in micro-USD. | | `agents[].createdAt` | body | string | — | CreatedAt is when the agent was defined, RFC 3339 in UTC to the second. | | `agents[].description` | body | string | — | Description is the one line another agent reads when deciding whether to call this one: the tool catalogue publishes it as the description of `agent_<name>`, falling back to "agent \" when it is empty. | | `agents[].emoji` | body | string | — | Emoji is the single glyph a caller picked when they had no image. | | `agents[].executionMode` | body | string | — | ExecutionMode is one-shot or long-running, and it decides who may start this agent. | | `agents[].id` | body | string | — | ID is the agent's stable handle, minted here as "agent\_" + 32 hex characters of crypto/rand. | | `agents[].lineage` | body | string\[] | — | Lineage is every agent above this one, nearest first — the parent, its parent, and so on to the agent a person defined. | | `agents[].max_task_micro_usd` | body | integer (int64) | — | MaxTaskMicroUSD is the ceiling for a single run, in micro-USD. | | `agents[].model` | body | string | — | Model is the Zen model this agent runs on, and it is always OUR name for it: writes normalize through cloud.ZenModel and the read normalizes again, so an upstream family name never leaves here even from a row written before that rule existed. | | `agents[].name` | body | string | — | Name is the agent's org-unique handle, matching ^\[A-Za-z0-9]\[A-Za-z0-9.\_-]{0,63}$. | | `agents[].parent` | body | string | — | Parent is the agent that spawned this one; absent for an agent a person defined. | | `agents[].period` | body | string | — | Period is the window the cap resets on: day, week or month. | | `agents[].runs` | body | integer (int64) | — | Runs is how many executions the org has recorded against this agent, counted at read time. | | `agents[].schedule` | body | string | — | Schedule is the 5-field cron the scheduler fires a long-running agent on, evaluated once a minute. | | `agents[].serviceAccountId` | body | string | — | ServiceAccountID is the IAM agent service account (\-\) a scheduled run is billed AS. | | `agents[].status` | body | string | — | Status is the agent's readiness: "ready", or "retired" for a built-in whose member has left Hanzo's team. | | `agents[].tools` | body | string\[] | — | Tools are the tool names this agent may call, and the list IS the authority: an agent that declares none gets none. | | `agents[].updatedAt` | body | string | — | UpdatedAt is the last time any field above was written, same format. | | `created` | body | integer (int64) | — | Created is how many new agent roles were created by this call. | | `templateVersion` | body | string | — | TemplateVersion is the shared template version applied. | | `updated` | body | integer (int64) | — | Updated is how many existing agent roles were updated idempotently in place without duplicating agents or budgets. | | `venture` | body | string | — | Venture is the venture slug the roster was applied for. | Failure carries the platform error shape — see [Errors](https://docs.hanzo.ai/docs/errors). ## Examples **CLI** ```bash hanzo agent roster create ``` **SDK** **.ts** ```ts import { Configuration, AgentApi } from 'hanzoai'; const api = new AgentApi(new Configuration({ accessToken: process.env.HANZO_API_KEY })); const { data } = await api.postAgentRoster({ roles: [{"cap_micro_usd":0,"duties":"","executionMode":"","expertise":""}], seedDefaultSeven: false }); ``` **.py** ```python from hanzoai.cloud import ApiClient, Configuration from hanzoai.cloud.api import AgentApi client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"])) result = AgentApi(client).post_agent_roster(roles=[{"cap_micro_usd":0,"duties":"","executionMode":"","expertise":""}], seed_default_seven=False) ``` **.go** ```go cfg := hanzoai.NewConfiguration() cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY")) client := hanzoai.NewAPIClient(cfg) resp, _, err := client.AgentAPI.PostAgentRoster(context.Background()).Execute() if err != nil { return err } ``` **.rs** ```rust use hanzo_client::apis::{configuration::Configuration, agent_api}; let mut cfg = Configuration::new(); cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok(); let result = agent_api::post_agent_roster(&cfg, Default::default()).await?; ``` **.java** ```java import ai.hanzo.cloud.ApiClient; import ai.hanzo.cloud.api.AgentApi; ApiClient client = new ApiClient(); client.setBearerToken(System.getenv("HANZO_API_KEY")); var result = new AgentApi(client).postAgentRoster(); ``` The method above is the one at the current release of the document. `hanzoai@8.5.914` (npm) and `hanzoai@8.5.914` (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 →](https://docs.hanzo.ai/docs/sdks) **HTTP** ```bash curl -X POST https://api.hanzo.ai/v1/agent/roster \ -H "Authorization: Bearer $HANZO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "roles": [ { "cap_micro_usd": 0, "duties": "", "executionMode": "", "expertise": "" } ], "seedDefaultSeven": false }' ``` **MCP** MCP reaches **agent** through the `agent` tool, which names its 51 operations with its own verbs — this one among them, under a name only MCP declares. `describe` explains any of them: ```bash 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_agents" } } }' ``` --- [Agent API](https://docs.hanzo.ai/docs/openapi/agent) · [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)