# Capsules

7 calls. Every request needs the `Authorization` header: see [the overview](https://docs.maitento.com/reference.md).

## `capsules.list`

```http
GET /capsules
```

Every definition of the tenant, or of one namespace with `{ namespace }`.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fcapsules).

**Response:** [`Capsule`](https://docs.maitento.com/reference/types/capsule.md)`[]` (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/capsules" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const capsules = await mt.capsules.list();
```
```python title="Python"
mt.capsules.list()
```

## `capsules.delete`

```http
DELETE /capsules/by-id/{id}
```

Deletes the definition (refused with a 400 while something still uses it or a run of it is going).

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=DELETE%20%2Fcapsules%2Fby-id%2F%7Bid%7D).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Response:** no body (204)

```bash title="curl"
curl -X DELETE "https://api.maitento.com/capsules/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
await mt.capsules.delete("a1a2a3a4-b1b2-4c1c-8d1d-e1e2e3e4e5e6");
```
```python title="Python"
mt.capsules.delete("c4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f")
```

## `capsules.get`

```http
GET /capsules/by-id/{id}
```

The definition with this id. Throws `NotFoundError` when there is none.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fcapsules%2Fby-id%2F%7Bid%7D).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Response:** [`Capsule`](https://docs.maitento.com/reference/types/capsule.md) (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/capsules/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const capsule = await mt.capsules.get("a1a2a3a4-b1b2-4c1c-8d1d-e1e2e3e4e5e6");
```
```python title="Python"
mt.capsules.get("c4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f")
```

## `capsules.start`

```http
PUT /capsules/by-id/{id}/versions/{versionNumber}/start
```

Starts a capsule (status `New`); by name the latest version, by `{ id, version? }` as for apps. Never retried.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=PUT%20%2Fcapsules%2Fby-id%2F%7Bid%7D%2Fversions%2F%7BversionNumber%7D%2Fstart).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |
| `versionNumber` | `integer` | yes |  |

**Request body:** [`CapsuleProcessStartRequest`](https://docs.maitento.com/reference/types/capsule-process-start-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `virtualFileSystemMounts` | [`CapsuleVirtualFileSystemMountInput`](https://docs.maitento.com/reference/types/capsule-virtual-file-system-mount.md#in-a-request)`[]` |  | Virtual file system mounts for this run. Unless `replaceMounts` is true, a non-empty list replaces the capsule's own mounts and an empty list keeps them. |
| `secretMounts` | [`CapsuleSecretMountInput`](https://docs.maitento.com/reference/types/capsule-secret-mount.md#in-a-request)`[]` |  | Secret mounts for this run. Unless `replaceMounts` is true, a non-empty list replaces the capsule's own secret mounts and an empty list keeps them. |
| `commands` | [`CapsuleProcessCommandInput`](https://docs.maitento.com/reference/types/capsule-process-command.md#in-a-request)`[]` |  | Shell commands to run, in order, after the capsule's startup commands. Only each one's `command`, `arguments`, `runAsUser` and `maximumDuration` are read. |
| `replaceMounts` | `boolean \| null` |  | True: `virtualFileSystemMounts` and `secretMounts` are this run's complete mounts, so an empty list means none of that kind. Null or false: an empty list keeps the capsule's own mounts of that kind. |

**Response:** [`CapsuleProcess`](https://docs.maitento.com/reference/types/capsule-process.md) (200)

```bash title="curl"
curl -X PUT "https://api.maitento.com/capsules/by-id/<id>/versions/<versionNumber>/start" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"virtualFileSystemMounts":[],"secretMounts":[],"commands":[],"replaceMounts":false}'
```
```ts title="TypeScript"
const run = await mt.capsules.start({ id: "a1a2a3a4-b1b2-4c1c-8d1d-e1e2e3e4e5e6", version: 2 });
```
```python title="Python"
mt.capsules.start(id="c4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f", version=2)
```

## `capsules.list`

```http
GET /namespaces/{namespaceName}/capsules
```

Every definition of the tenant, or of one namespace with `{ namespace }`.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fnamespaces%2F%7BnamespaceName%7D%2Fcapsules).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `namespaceName` | `string` | yes |  |

**Response:** [`Capsule`](https://docs.maitento.com/reference/types/capsule.md)`[]` (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/namespaces/<namespaceName>/capsules" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const capsules = await mt.capsules.list({ namespace: "support" });
```
```python title="Python"
mt.capsules.list(namespace="demo")
```

## `capsules.getByName`

```http
GET /namespaces/{namespaceName}/capsules/by-name/{name}
```

The definition with this name in the namespace. Throws `NotFoundError` when there is none.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fnamespaces%2F%7BnamespaceName%7D%2Fcapsules%2Fby-name%2F%7Bname%7D).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `namespaceName` | `string` | yes |  |
| `name` | `string` | yes |  |

**Response:** [`Capsule`](https://docs.maitento.com/reference/types/capsule.md) (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/namespaces/<namespaceName>/capsules/by-name/<name>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const capsule = await mt.capsules.getByName("python-sandbox", { namespace: "support" });
```
```python title="Python"
mt.capsules.get_by_name("python-sandbox", namespace="demo")
```

## `capsules.start`

```http
PUT /namespaces/{namespaceName}/capsules/by-name/{name}/versions/latest/start
```

Starts a capsule (status `New`); by name the latest version, by `{ id, version? }` as for apps. Never retried.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=PUT%20%2Fnamespaces%2F%7BnamespaceName%7D%2Fcapsules%2Fby-name%2F%7Bname%7D%2Fversions%2Flatest%2Fstart).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `namespaceName` | `string` | yes |  |
| `name` | `string` | yes |  |

**Request body:** [`CapsuleProcessStartRequest`](https://docs.maitento.com/reference/types/capsule-process-start-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `virtualFileSystemMounts` | [`CapsuleVirtualFileSystemMountInput`](https://docs.maitento.com/reference/types/capsule-virtual-file-system-mount.md#in-a-request)`[]` |  | Virtual file system mounts for this run. Unless `replaceMounts` is true, a non-empty list replaces the capsule's own mounts and an empty list keeps them. |
| `secretMounts` | [`CapsuleSecretMountInput`](https://docs.maitento.com/reference/types/capsule-secret-mount.md#in-a-request)`[]` |  | Secret mounts for this run. Unless `replaceMounts` is true, a non-empty list replaces the capsule's own secret mounts and an empty list keeps them. |
| `commands` | [`CapsuleProcessCommandInput`](https://docs.maitento.com/reference/types/capsule-process-command.md#in-a-request)`[]` |  | Shell commands to run, in order, after the capsule's startup commands. Only each one's `command`, `arguments`, `runAsUser` and `maximumDuration` are read. |
| `replaceMounts` | `boolean \| null` |  | True: `virtualFileSystemMounts` and `secretMounts` are this run's complete mounts, so an empty list means none of that kind. Null or false: an empty list keeps the capsule's own mounts of that kind. |

**Response:** [`CapsuleProcess`](https://docs.maitento.com/reference/types/capsule-process.md) (200)

```bash title="curl"
curl -X PUT "https://api.maitento.com/namespaces/<namespaceName>/capsules/by-name/<name>/versions/latest/start" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"virtualFileSystemMounts":[],"secretMounts":[],"commands":[],"replaceMounts":false}'
```
```ts title="TypeScript"
const run = await mt.capsules.start({ name: "python-sandbox", namespace: "support" });
```
```python title="Python"
mt.capsules.start("python-sandbox", namespace="demo")
```