Reference

projects

Projects inside an org: what device sessions, runs and builds belong to. Index · shared schemas · errors.

Procedure	Summary	REST	MCP tool	Stability
`projects.list`	List the org's projects in the caller's view, oldest first; archived ones only when asked	`GET`	—	experimental
`projects.get`	Get a project	`GET`	—	experimental
`projects.create`	Create a project (CONFLICT when the slug or externalRef is taken in the org)	`POST`	—	experimental
`projects.update`	Rename a project or change its slug	`POST`	—	experimental
`projects.archive`	Archive a project: it leaves the default list; its data stays (idempotent)	`POST`	—	experimental
`projects.resolve`	Find the project mapped to a caller's externalRef (NOT_FOUND when none is in view)	`GET`	—	experimental
`projects.ensure`	Return the project mapped to an externalRef, creating it if none exists; concurrent first calls create exactly one	`POST`	—	experimental

`projects.list`

List the org's projects in the caller's view, oldest first; archived ones only when asked


REST	`GET /v1/projects/list` (input as query parameters)
RPC	`/rpc/v2/projects/list`
MCP	not a tool (a cloud platform procedure; the cloud MCP surface is the curated device tools); hints: read-only, idempotent
Auth	`projects:read`
Tenancy	`org`
Troupe Cloud	answered by the control plane
Stability	experimental, since 1.0

Input:

TypeScript

{ orgId: OrgId; includeArchived?: boolean; limit?: PageLimit; cursor?: PageCursor }

Output:

TypeScript

{ projects: Project[]; nextCursor?: string }

Errors: U, NOT_FOUND.

Named types: OrgId, PageCursor, PageLimit, Project.

`projects.get`

Get a project


REST	`GET /v1/projects/get` (input as query parameters)
RPC	`/rpc/v2/projects/get`
MCP	not a tool (a cloud platform procedure; the cloud MCP surface is the curated device tools); hints: read-only, idempotent
Auth	`projects:read`
Tenancy	`project`
Troupe Cloud	answered by the control plane
Stability	experimental, since 1.0

Input:

TypeScript

{ projectId: ProjectId }

Output:

TypeScript

{ project: Project }

Errors: U, NOT_FOUND.

Named types: Project, ProjectId.

`projects.create`

Create a project (CONFLICT when the slug or externalRef is taken in the org)


REST	`POST /v1/projects/create` (input as a JSON body)
RPC	`/rpc/v2/projects/create`
MCP	not a tool (a cloud platform procedure; the cloud MCP surface is the curated device tools); hints: none
Auth	`projects:write`
Tenancy	`org`
Troupe Cloud	answered by the control plane
Stability	experimental, since 1.0

Input:

TypeScript

{ orgId: OrgId; name: DisplayName; slug?: Slug; externalRef?: ExternalRef }

Output:

TypeScript

{ project: Project }

Errors: U, NOT_FOUND, ORG_SUSPENDED, CONFLICT.

Named types: DisplayName, ExternalRef, OrgId, Project, Slug.

`projects.update`

Rename a project or change its slug


REST	`POST /v1/projects/update` (input as a JSON body)
RPC	`/rpc/v2/projects/update`
MCP	not a tool (a cloud platform procedure; the cloud MCP surface is the curated device tools); hints: idempotent
Auth	`projects:write`
Tenancy	`project`
Troupe Cloud	answered by the control plane
Stability	experimental, since 1.0

Input:

TypeScript

{ projectId: ProjectId; name?: DisplayName; slug?: Slug }

Output:

TypeScript

{ project: Project }

Errors: U, NOT_FOUND, ORG_SUSPENDED, CONFLICT.

Named types: DisplayName, Project, ProjectId, Slug.

`projects.archive`

Archive a project: it leaves the default list; its data stays (idempotent)


REST	`POST /v1/projects/archive` (input as a JSON body)
RPC	`/rpc/v2/projects/archive`
MCP	not a tool (a cloud platform procedure; the cloud MCP surface is the curated device tools); hints: idempotent, destructive
Auth	`projects:write`
Tenancy	`project`
Troupe Cloud	answered by the control plane
Stability	experimental, since 1.0

Input:

TypeScript

{ projectId: ProjectId }

Output:

TypeScript

{ project: Project }

Errors: U, NOT_FOUND, CONFLICT.

Named types: Project, ProjectId.

`projects.resolve`

Find the project mapped to a caller's externalRef (NOT_FOUND when none is in view)


REST	`GET /v1/projects/resolve` (input as query parameters)
RPC	`/rpc/v2/projects/resolve`
MCP	not a tool (a cloud platform procedure; the cloud MCP surface is the curated device tools); hints: read-only, idempotent
Auth	`projects:read`
Tenancy	`org`
Troupe Cloud	answered by the control plane
Stability	experimental, since 1.0

Input:

TypeScript

{ orgId: OrgId; externalRef: ExternalRef }

Output:

TypeScript

{ project: Project }

Errors: U, NOT_FOUND.

Named types: ExternalRef, OrgId, Project.

`projects.ensure`

Return the project mapped to an externalRef, creating it if none exists; concurrent first calls create exactly one


REST	`POST /v1/projects/ensure` (input as a JSON body)
RPC	`/rpc/v2/projects/ensure`
MCP	not a tool (a cloud platform procedure; the cloud MCP surface is the curated device tools); hints: idempotent
Auth	`projects:write`
Tenancy	`org`
Troupe Cloud	answered by the control plane
Stability	experimental, since 1.0

Input:

TypeScript

{ orgId: OrgId; externalRef: ExternalRef; name?: DisplayName; slug?: Slug }

Output:

TypeScript

{ project: Project; created: boolean }

Errors: U, NOT_FOUND, ORG_SUSPENDED, CONFLICT.

Named types: DisplayName, ExternalRef, OrgId, Project, Slug.