Create an empty project with its default `main` branch — add services afterwards
POSThttps://api.instacloud.com/orgs/{orgId}/projects
Token scope: account · org — read-only tokens refused (not a GET).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
orgId | path | string | yes |
Request body
application/json
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes |
Responses
201
Default Response
| Field | Type | Required | Description |
|---|---|---|---|
project | object | no | |
project.id | string | no | |
project.org_id | string | no | |
project.owner_user_id | string | no | Better Auth user id (opaque string, not a UUID) |
project.name | string | no | |
project.status | "active" | "error" | "deleting" | "deleted" | no | |
project.created_at | string | no | |
defaultBranch | object | no | |
defaultBranch.id | string | no | |
defaultBranch.name | string | no | |
resources | object[] | no | |
resources.kind | "neon" | "insta-db" | "s3" | "fly" | "insta-compute" | no | |
resources.provider | "fly" | "insta-compute" | no | Compute plane actually backing a compute resource, derived from its provider_ref rather than its kind. Absent when it cannot be determined from the row — clients must then assert no provider rather than assume one from `kind`. |
resources.status | 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. |
400
Default Response
| Field | Type | Required | Description |
|---|---|---|---|
error | string | yes |
403
Default Response
| Field | Type | Required | Description |
|---|---|---|---|
error | string | yes |
409
Default Response
| Field | Type | Required | Description |
|---|---|---|---|
error | string | yes |
429
Default Response
| Field | Type | Required | Description |
|---|---|---|---|
error | string | yes |