Documentation menu

Create branch

POSThttps://api.instacloud.com/projects/{projectId}/branches

Token scope: account · org · project — read-only tokens refused (not a GET).

Create a branch (database branch + Tigris fork + cloned compute groups, or empty)

Parameters

Name	In	Type	Required	Description
`projectId`	path	`string`	yes

application/json

Field	Type	Required	Description
`name`	`string`	yes	lower-kebab: a-z, 0-9, hyphen (max 39)
`from`	`string`	no	parent branch name
`empty`	`boolean`	no	create the branch and nothing else: none of the parent's services are forked and none of its branch-scoped secrets are copied (project-scoped secrets still apply). `from` only sets the parent link.

Default Response

Field	Type	Required	Description
`branch`	`object`	no
`branch.id`	`string`	no
`branch.project_id`	`string`	no
`branch.name`	`string`	no
`branch.parent_branch_id`	`string \| null`	no
`branch.is_default`	`boolean`	no
`branch.status`	`"creating" \| "active" \| "error" \| "deleting"`	no
`branch.created_at`	`string`	no
`nextActions`	`object[]`	no
`nextActions.op`	`string`	yes	Neutral logical action id, e.g. "service.add" — NOT an operationId or a CLI/MCP tool name; each client maps it to its own surface.
`nextActions.reason`	`string`	yes	Natural-language, human/LLM-facing "why do this now".
`nextActions.args`	`object`	no	Suggested, flat named arguments; "<placeholder>"s where a value is unknown.
`nextActions.gated`	`boolean`	no	True if the action passes a governance gate.

Default Response

Field	Type	Required
`status`	`string`	yes
`approvalId`	`string`	yes
`action`	`string`	yes
`actions`	`string[]`	yes
`message`	`string`	yes
`url`	`string`	yes

Default Response

Field	Type	Required	Description
`error`	`string`	yes

Default Response

Field	Type	Required	Description
`error`	`string`	yes

Default Response

Field	Type	Required	Description
`error`	`string`	yes

Default Response

Field	Type	Required	Description
`error`	`string`	yes