# ProjectService

**Spinbox is experimental: APIs change and data may be lost.** What is built and what proves it is on [Status](https://docs.spinbox.dev/reference/status.md); what Spinbox does not do is on [Limitations](https://docs.spinbox.dev/overview/limitations.md).

> spin.v1.ProjectService: each procedure, its request and its response.

<!-- Generated by tools/refgen from spin:internal/controlplane/apidocs/spin.v1.openapi.json. Edit the source, not this file. -->

ProjectService is the installation's projects (spin#720): a repository and the shape of the. workspace that opens it (CreateWorkspaceRequest.project_id). Anybody signed in makes one where. the installation lets everybody (the setting project_creation), and is its first admin. A project is seen by everybody while it is shared with everyone, and otherwise by its admins and. whom it is shared with; the instance's admins see and administer every one. Whoever sees one. opens workspaces from it, in a team of theirs.

## CreateProject

`POST /spin.v1.ProjectService/CreateProject`

**Request**

| Field | Type | What it is |
|---|---|---|
| `name` | string |  |
| `slug` | string | Made from the name when empty |
| `description` | string |  |
| `repository` | string |  |
| `ref` | string |  |
| `image` | string |  |
| `preset` | string |  |
| `networkTags` | list of string |  |
| `prebuildRefs` | list of string |  |
| `prebuildRebaseEvery` | integer (int32) | Zero is the installation's default |
| `prebuildKeep` | integer (int32) | Zero is one: the newest of each ref |

**Response**

| Field | Type | What it is |
|---|---|---|
| `project` | [Project](https://docs.spinbox.dev/reference/api/types.md#project) |  |

## DeleteProject

`POST /spin.v1.ProjectService/DeleteProject`

**Request**

| Field | Type | What it is |
|---|---|---|
| `id` | string |  |

**Response**

No fields: `{}`.

## GetPrebuild

`POST /spin.v1.ProjectService/GetPrebuild`

One of them whole, with what its build's create tasks wrote, to whoever sees the project.

**Request**

| Field | Type | What it is |
|---|---|---|
| `projectId` | string |  |
| `prebuildId` | string |  |

**Response**

| Field | Type | What it is |
|---|---|---|
| `prebuild` | [Prebuild](https://docs.spinbox.dev/reference/api/types.md#prebuild) |  |

## GetProject

`POST /spin.v1.ProjectService/GetProject`

**Request**

| Field | Type | What it is |
|---|---|---|
| `id` | string |  |
| `slug` | string |  |

**Response**

| Field | Type | What it is |
|---|---|---|
| `project` | [Project](https://docs.spinbox.dev/reference/api/types.md#project) |  |

## GetProjectCosts

`POST /spin.v1.ProjectService/GetProjectCosts`

What a project cost in the month in progress, to its admins and nobody else, as ListProjectWorkspaces: everybody's workspaces of it summed, its prebuilds' builds included, and a month of what its prebuilds keep. A sum, never by workspace: one workspace's cost says how much its owner works, which a project's admin who is not their team's is not told. Read from the bill as the installation last read it, never from the cloud.

**Request**

| Field | Type | What it is |
|---|---|---|
| `projectId` | string |  |

**Response**

| Field | Type | What it is |
|---|---|---|
| `month` | `Timestamp` | The month in progress: its first instant, UTC. |
| `readAt` | `Timestamp` | When the bill was last read; unset where it never was - an installation with no bill scope - and then nothing below is known and nothing is to be drawn. |
| `currency` | string | ISO 4217; every amount here is in millionths of it. |
| `workspaces` | [CostShare](https://docs.spinbox.dev/reference/api/types.md#costshare) | Its workspaces' shares summed, deleted ones and its prebuilds' builds included: a workspace is the project's it opened, whoever's it was. |
| `prebuilds` | [PrebuildsKept](https://docs.spinbox.dev/reference/api/types.md#prebuildskept) |  |

## ListPrebuilds

`POST /spin.v1.ProjectService/ListPrebuilds`

A project's prebuilds, to whoever sees it; and a build of one of its refs now, by its admins, rather than at the next look.

**Request**

| Field | Type | What it is |
|---|---|---|
| `projectId` | string |  |

**Response**

| Field | Type | What it is |
|---|---|---|
| `prebuilds` | list of [Prebuild](https://docs.spinbox.dev/reference/api/types.md#prebuild) | Newest first. |
| `storageMeasuredAt` | `Timestamp` | When storage-gc last read the store, which each stored_bytes is as of; unset before it has. |
| `retireUnusedDays` | integer (int32) | The installation's prebuild_retire_unused_days: a ready prebuild nobody opened a workspace from in this many days is retired, its ref's newest included. Zero retires none for that. |
| `refsNotFound` | list of [PrebuildRefNotFound](https://docs.spinbox.dev/reference/api/types.md#prebuildrefnotfound) | The refs the project prebuilds that its forge says the repository has not - a branch deleted since it was named - as the prebuilds job last found them: nothing is built of one until the forge has it again or the project names it no longer. |

## ListProjectWorkspaces

`POST /spin.v1.ProjectService/ListProjectWorkspaces`

Everybody's workspaces open on a project, to its admins and nobody else: a person it is only shared with is refused, and reads their own with ListWorkspaces.

**Request**

| Field | Type | What it is |
|---|---|---|
| `projectId` | string |  |

**Response**

| Field | Type | What it is |
|---|---|---|
| `workspaces` | list of [ProjectWorkspace](https://docs.spinbox.dev/reference/api/types.md#projectworkspace) | Newest first, and at most 500. Not a prebuild's build, and not a deleted one. |

## ListProjects

`POST /spin.v1.ProjectService/ListProjects`

**Request**

No fields: `{}`.

**Response**

| Field | Type | What it is |
|---|---|---|
| `projects` | list of [Project](https://docs.spinbox.dev/reference/api/types.md#project) |  |

## RunPrebuild

`POST /spin.v1.ProjectService/RunPrebuild`

**Request**

| Field | Type | What it is |
|---|---|---|
| `projectId` | string |  |
| `ref` | string | One of the project's prebuild refs. |

**Response**

| Field | Type | What it is |
|---|---|---|
| `prebuild` | [Prebuild](https://docs.spinbox.dev/reference/api/types.md#prebuild) | The build, or the one already running at that commit. |

## ShareProject

`POST /spin.v1.ProjectService/ShareProject`

**Request**

| Field | Type | What it is |
|---|---|---|
| `id` | string |  |
| `sharedWithEveryone` | boolean |  |
| `userIds` | list of string |  |
| `teamIds` | list of string |  |
| `adminIds` | list of string |  |

**Response**

| Field | Type | What it is |
|---|---|---|
| `project` | [Project](https://docs.spinbox.dev/reference/api/types.md#project) |  |

## UpdateProject

`POST /spin.v1.ProjectService/UpdateProject`

Changed, shared and deleted by its admins. A project with a workspace open on it is not deleted.

**Request**

| Field | Type | What it is |
|---|---|---|
| `id` | string |  |
| `name` | string |  |
| `slug` | string |  |
| `description` | string |  |
| `repository` | string |  |
| `ref` | string |  |
| `image` | string |  |
| `preset` | string |  |
| `networkTags` | list of string |  |
| `prebuildRefs` | list of string |  |
| `prebuildRebaseEvery` | integer (int32) |  |
| `prebuildKeep` | integer (int32) | Zero is one, as at create |

**Response**

| Field | Type | What it is |
|---|---|---|
| `project` | [Project](https://docs.spinbox.dev/reference/api/types.md#project) |  |
