Create review

Runs the scheduled review of repeated failures, missing expertise, and human review effort across the organization's runs, briefs, and observed coverage gaps, producing role candidate proposals with concrete examples, a micro-USD cost estimate, and a reporting line.

POST /v1/agent/proposals/review

Agent → · All API references → · Get started →

Address	`https://api.hanzo.ai/v1/agent/proposals/review`
Method	`POST`
Operation	`post_agent_proposals_review`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Request

12 fields, body application/json (required).

Field	In	Type	Required	Description
`failureThreshold`	body	integer (int64)	—	FailureThreshold is the minimum number of failed runs on an agent or function that triggers a role proposal; defaults to 2.
`observedGaps`	body	agent.RoleGapInput[]	—	ObservedGaps are explicit coverage gaps, unsupported-claim clusters, or review-effort spikes to evaluate alongside stored run history.
`observedGaps[].estimatedMicroUsd`	body	integer (int64)	—	EstimatedMicroUSD is the estimated period cost for the proposed role in integer micro-USD.
`observedGaps[].examples`	body	string[]	—	Examples lists concrete run IDs, unsupported claims, or reviewer corrections demonstrating the gap.
`observedGaps[].failureCount`	body	integer (int64)	—	FailureCount is how many repeated failures were observed in this area.
`observedGaps[].function`	body	string	—	Function is the studio function where the coverage gap or failure occurred (e.g. "regulatory-clinical").
`observedGaps[].reportingLine`	body	string	—	ReportingLine names the manager agent handle the proposed role will report to; defaults to "venture-lead".
`observedGaps[].reviewSeconds`	body	integer (int64)	—	ReviewSeconds is the human domain-review effort recorded on this gap in seconds.
`observedGaps[].roleName`	body	string	—	RoleName is the suggested agent handle for the proposed specialist role; generated from Function and Topic when omitted.
`observedGaps[].title`	body	string	—	Title is the human-readable title for the proposed role.
`observedGaps[].topic`	body	string	—	Topic describes the missing expertise or recurring failure domain (e.g. "laboratory-lims-telemetry-integration").
`venture`	body	string	—	Venture optionally scopes the nightly review to a specific venture slug.

Response

Status	Body	Meaning
`200`	agent.reviewProposalsOut	ok
`default`	problem-details	refused

200 body — 22 fields.

Field	In	Type	Always	Description
`created`	body	integer (int64)	—	Created is how many new role proposals were generated during this review pass.
`proposals`	body	agent.RoleProposal[]	—	Proposals are the active role candidate proposals resulting from the review.
`proposals[].agentId`	body	string	—	AgentID is the created agent's handle (`agent_...`) once the proposal has been approved; empty when pending or rejected.
`proposals[].cap_micro_usd`	body	integer (int64)	—	CapMicroUSD is the period budget cap in integer micro-USD that will be set on the created agent.
`proposals[].createdAt`	body	integer (int64)	—	CreatedAt is when the proposal was generated, as Unix seconds.
`proposals[].decidedAt`	body	integer (int64)	—	DecidedAt is when the proposal was approved or rejected, as Unix seconds.
`proposals[].decidedBy`	body	string	—	DecidedBy records the subject who approved or rejected the proposal.
`proposals[].decisionReason`	body	string	—	DecisionReason records the operator's note when approving or rejecting.
`proposals[].estimatedMicroUsd`	body	integer (int64)	—	EstimatedMicroUSD is the estimated monthly spend for this role in integer micro-USD.
`proposals[].examples`	body	string[]	—	Examples are the concrete failed runs, unsupported claims, or review bottlenecks backing the proposal.
`proposals[].function`	body	string	—	Function is the studio function this role candidate belongs to.
`proposals[].id`	body	string	—	ID is the stable proposal identifier (`prop_...`).
`proposals[].instructions`	body	string	—	Instructions is the system prompt that will govern the proposed role.
`proposals[].max_task_micro_usd`	body	integer (int64)	—	MaxTaskMicroUSD is the single-run budget ceiling in integer micro-USD that will be set on the created agent.
`proposals[].name`	body	string	—	Name is the org-unique agent handle that will be created if the proposal is approved.
`proposals[].period`	body	string	—	Period is the budget reset window: day, week, or month.
`proposals[].rationale`	body	string	—	Rationale explains why the nightly review proposed this role candidate.
`proposals[].reportingLine`	body	string	—	ReportingLine is the manager agent handle (`parent`) the proposed role reports to.
`proposals[].status`	body	string	—	Status is the proposal's decision state: pending, approved, or rejected.
`proposals[].title`	body	string	—	Title is the human-readable title of the proposed role.
`proposals[].tools`	body	string[]	—	Tools are the MCP tool names the proposed role will be granted.
`proposals[].venture`	body	string	—	Venture is the venture slug the role candidate is proposed for.

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo agent proposals review

.ts

.py

.go

.rs

.java

import { Configuration, AgentApi } from 'hanzoai';

const api = new AgentApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postAgentProposalsReview({ failureThreshold: 0, observedGaps: [{"estimatedMicroUsd":0,"examples":["<examples>"],"failureCount":0,"function":"<function>"}] });

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_proposals_review(failure_threshold=0, observed_gaps=[{"estimatedMicroUsd":0,"examples":["<examples>"],"failureCount":0,"function":"<function>"}])

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

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

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_proposals_review(&cfg, Default::default()).await?;

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).postAgentProposalsReview();

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 -X POST https://api.hanzo.ai/v1/agent/proposals/review \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "failureThreshold": 0,
       "observedGaps": [
         {
           "estimatedMicroUsd": 0,
           "examples": [
             "<examples>"
           ],
           "failureCount": 0,
           "function": "<function>"
         }
       ]
     }'

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:

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 · All Hanzo APIs · Interactive reference

Was this page useful?

Broken link or missing step? Drop it in #docs on Discord or open a PR.

PreviousCreate decide NextCreate roster