Create ventures

POST /v1/guide/ventures

Guide → · All API references → · Get started →

Address	`https://api.hanzo.ai/v1/guide/ventures`
Method	`POST`
Operation	`post_guide_ventures`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Creates or imports a venture under the caller studio's portfolio, captures its thesis, sponsor, owner, initial budget and seed evidence, and enrolls its isolated venture organization in a versioned Guide playbook (defaulting to venture). Repeated or interrupted calls with the same slug resume idempotently without duplicating the venture, its team checkpoint, or its initial budget.

Request

13 fields, body application/json (required).

Field	In	Type	Required	Description
`evidence`	body	string[]	—	Evidence lists initial source citations or evidence URIs for the venture.
`imported`	body	boolean	—	Imported marks whether this venture is being imported from an existing workspace.
`initialBudgetMicroUSD`	body	integer (int64)	—	InitialBudgetMicroUSD is the initial budget allocated to the venture in integer micro-USD.
`members`	body	string[]	—	Members optionally assigns initial teammate subjects access to this venture.
`owner`	body	string	—	Owner names the venture lead (person or lead agent handle) driving the venture.
`playbook`	body	string	—	Playbook selects a brand playbook name (such as "venture") or supplies a raw YAML/JSON curriculum document; empty defaults to "venture".
`slug`	body	string	—	Slug is the venture's unique handle inside the studio portfolio (e.g. "vet-clinic-scheduling").
`sponsor`	body	string	—	Sponsor names the studio partner or executive sponsoring the venture.
`stage`	body	string	—	Stage sets the initial studio funnel stage (intake, discovery, validation, formation, scaling); defaults to "intake".
`teamSeeded`	body	boolean	—	TeamSeeded marks whether the venture's initial agent roster has been seeded.
`thesis`	body	string	—	Thesis is the falsifiable venture hypothesis to test before entity formation.
`title`	body	string	—	Title is the human-readable name of the venture.
`ventureOrg`	body	string	—	VentureOrg optionally names the explicit venture organization slug; when omitted it defaults to "<studioOrg>--<slug>".

Response

Status	Body	Meaning
`200`	guide.VentureRecord	ok
`default`	problem-details	refused

200 body — 39 fields.

Field	In	Type	Always	Description
`createdAt`	body	integer (int64)	—	CreatedAt is when the venture was first registered in the portfolio, as Unix seconds.
`evidence`	body	string[]	—	Evidence lists the source citations and evidence URIs attached to the venture.
`failedRuns`	body	integer (int64)	—	FailedRuns is how many specialist or automation runs have failed and await retry or review.
`formationId`	body	string	—	FormationID is the legal entity formation identifier from /v1/company once the venture advances to formation.
`imported`	body	boolean	—	Imported is true when the venture was imported into the studio rather than started from scratch.
`initialBudgetMicroUSD`	body	integer (int64)	—	InitialBudgetMicroUSD is the initial venture budget in integer micro-USD, allocated at creation.
`latestEvidence`	body	string	—	LatestEvidence is the most recently recorded evidence citation or URI for this venture.
`members`	body	string[]	—	Members lists the teammate subjects explicitly assigned access to this venture.
`owner`	body	string	—	Owner is the venture lead (person or lead agent handle) accountable for executing the playbook.
`pendingDecisions`	body	integer (int64)	—	PendingDecisions is how many research decisions, role proposals, or external actions await human approval.
`playbookVersion`	body	string	—	PlaybookVersion is the version string of the Guide curriculum enrolled for this venture.
`progress`	body	guide.progressView	—
`progress.done`	body	integer (int64)	—	Done counts steps that are FINISHED — done and skipped alike, since a step the org deliberately passed over is not still owed.
`progress.next`	body	string	—	Next is the id of the step to do next: the first available, unfinished step in authoring order.
`progress.percent`	body	integer (int64)	—	Percent is done/total as a whole number 0-100, rounded, so a caller renders a bar without recomputing it.
`progress.total`	body	integer (int64)	—	Total is how many steps this org's journey holds — the ENABLED steps of the playbook, so it shrinks when an operator disables one and does not match the authored step count.
`resumed`	body	boolean	—	Resumed is true when a repeated or interrupted create call resumed an existing venture without duplicating budget or team.
`setup`	body	guide.VentureSetupState	—
`setup.budgetAllocated`	body	boolean	—	BudgetAllocated is true once the initial micro-USD budget has been committed, preventing duplicate allocation.
`setup.members`	body	string[]	—	Members lists the teammate subjects explicitly assigned access to this venture.
`setup.orgProvisioned`	body	boolean	—	OrgProvisioned is true once the venture's isolated organization store has been opened.
`setup.playbookEnrolled`	body	boolean	—	PlaybookEnrolled is true once the versioned curriculum has been persisted in the venture's store.
`setup.revokedMembers`	body	string[]	—	RevokedMembers lists teammate subjects whose seat access to this venture has been revoked.
`setup.teamSeeded`	body	boolean	—	TeamSeeded is true once the venture's team roster has been enrolled.
`slug`	body	string	—	Slug is the venture's unique handle inside the studio portfolio.
`spendMicroUSD`	body	integer (int64)	—	SpendMicroUSD is the cumulative spend recorded against this venture in integer micro-USD.
`sponsor`	body	string	—	Sponsor is the studio partner or executive sponsoring the venture.
`stage`	body	string	—	Stage is the venture's position in the studio funnel: intake, discovery, validation, formation, or scaling.
`status`	body	string	—	Status is the venture's operating state: active, paused, forming, formed, or offboarded.
`studioOrg`	body	string	—	StudioOrg is the parent studio organization operating the portfolio.
`templates`	body	guide.Page[]	—	Templates are the shared studio templates from the playbook visible in this venture.
`templates[].body`	body	string	—	Body is the reusable prompt or snippet itself.
`templates[].enabled`	body	boolean	—	Enabled is the admin lever.
`templates[].id`	body	string	—	ID is the slug a step references to pull this template in.
`templates[].title`	body	string	—	Title names the template in the authoring plane and in a picker.
`thesis`	body	string	—	Thesis is the falsifiable venture hypothesis being tested before entity formation.
`title`	body	string	—	Title is the human-readable name of the venture.
`updatedAt`	body	integer (int64)	—	UpdatedAt is when the venture record was last updated, as Unix seconds.
`ventureOrg`	body	string	—	VentureOrg is the isolated organization namespace holding this venture's private progress, documents, runs, and secrets.

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo guide ventures create

.ts

.py

.go

.rs

.java

import { Configuration, GuideApi } from 'hanzoai';

const api = new GuideApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postGuideVentures({ evidence: ["<evidence>"], imported: false });

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

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = GuideApi(client).post_guide_ventures(evidence=["<evidence>"], imported=False)

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

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

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

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

let result = guide_api::post_guide_ventures(&cfg, Default::default()).await?;

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

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

var result = new GuideApi(client).postGuideVentures();

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/guide/ventures \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "evidence": [
         "<evidence>"
       ],
       "imported": false
     }'

MCP reaches guide through the guide tool, which names its 18 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_guides"
         }
       }
     }'

Guide 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 lifecycle NextReplace curriculum