# Apps

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

## `apps.list`

```http
GET /apps
```

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%2Fapps).

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

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

## `apps.delete`

```http
DELETE /apps/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%2Fapps%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/apps/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
await mt.apps.delete("1b4e28ba-2fa1-41d2-883f-0016d3cca427");
```
```python title="Python"
mt.apps.delete("a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d")
```

## `apps.get`

```http
GET /apps/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%2Fapps%2Fby-id%2F%7Bid%7D).

**Path parameters**

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

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

```bash title="curl"
curl -X GET "https://api.maitento.com/apps/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const app = await mt.apps.get("1b4e28ba-2fa1-41d2-883f-0016d3cca427");
```
```python title="Python"
mt.apps.get("a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d")
```

## `apps.start`

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

Starts a run (status `New`): by name, the latest version; by `{ id, version }`, that version; by `{ id }`, the latest enabled version. 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%2Fapps%2Fby-id%2F%7Bid%7D%2Fversions%2F%7BversionNumber%7D%2Fstart).

**Path parameters**

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

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

| Field | Type | Required | Description |
|---|---|---|---|
| `inputs` | [`NameValuePair`](https://docs.maitento.com/reference/types/name-value-pair.md)`[]` | yes | A value for every input the app declares (the parameters of its `main`), by name. Every declared input is required; a name the app doesn't declare is ignored. |
| `credentials` | [`InteractionProcessCredentialRequest`](https://docs.maitento.com/reference/types/interaction-process-credential-request.md)`[] \| null` |  | Model keys for this run, in the order they are tried. Every interaction the app starts uses them before your tenant's model keys. Null or empty: only your tenant's keys are used. |
| `allowMaitentoFallback` | `boolean \| null` |  | Whether an interaction this app starts may use Maitento's own key for a provider once no key of yours for it is left. Null means no. |
| `credentialStack` | `string \| null` |  | The credential stack the run uses, by id or name, and every interaction and code pipeline it starts. Its credentials serve every model call, in the stack's order, and Maitento's own keys are never used. Leave it out to use the app's own stack, then the namespace's default, then your tenant's. Can't be combined with `credentials`. |
| `aiModelOverrides` | [`AiModelOverrideRequestInput`](https://docs.maitento.com/reference/types/ai-model-override-request.md#in-a-request)`[] \| null` |  | Model overrides for named agents, applied to every interaction this app starts. Null or empty: agents use the models their definitions name. |
| `webDownloadPartitionId` | `uuid \| null` |  | The temporary knowledge base (partition) that pages fetched by the web tools of every interaction and code pipeline this app starts are kept in, passed on to the apps it starts. Ignored unless it is one of your temporary knowledge bases. Null: each run uses its namespace's default, then the tenant's. |
| `webAccessOverrides` | [`WebAccessOverrideInput`](https://docs.maitento.com/reference/types/web-access-override.md#in-a-request)`[] \| null` |  | Web tool overrides (on or off, for all agents or one by name) applied to every interaction this app starts. |

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

```bash title="curl"
curl -X PUT "https://api.maitento.com/apps/by-id/<id>/versions/<versionNumber>/start" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"inputs":[]}'
```
```ts title="TypeScript"
const run = await mt.apps.start({ id: "1b4e28ba-2fa1-41d2-883f-0016d3cca427", version: 3 }, { inputs: { customerId: "C-1042" } });
```
```python title="Python"
mt.apps.start(id="a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", version=3, inputs={"ticket": "My invoice is wrong"})
```

## `apps.list`

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

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%2Fapps).

**Path parameters**

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

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

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

## `apps.create`

```http
POST /namespaces/{namespaceName}/apps
```

Creates an empty app (its versions come from deploys).

**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=POST%20%2Fnamespaces%2F%7BnamespaceName%7D%2Fapps).

**Path parameters**

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

**Request body:** [`AppCreateRequest`](https://docs.maitento.com/reference/types/app-create-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | yes | The app's name, unique within its namespace. At most 150 characters. |

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

```bash title="curl"
curl -X POST "https://api.maitento.com/namespaces/<namespaceName>/apps" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"name":"..."}'
```
```ts title="TypeScript"
const app = await mt.apps.create({ name: "refund-flow" }, { namespace: "support" });
```
```python title="Python"
mt.apps.create("triage", namespace="demo")
```

## `apps.getByName`

```http
GET /namespaces/{namespaceName}/apps/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%2Fapps%2Fby-name%2F%7Bname%7D).

**Path parameters**

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

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

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

## `apps.start`

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

Starts a run (status `New`): by name, the latest version; by `{ id, version }`, that version; by `{ id }`, the latest enabled version. 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%2Fapps%2Fby-name%2F%7Bname%7D%2Fversions%2Flatest%2Fstart).

**Path parameters**

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

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

| Field | Type | Required | Description |
|---|---|---|---|
| `inputs` | [`NameValuePair`](https://docs.maitento.com/reference/types/name-value-pair.md)`[]` | yes | A value for every input the app declares (the parameters of its `main`), by name. Every declared input is required; a name the app doesn't declare is ignored. |
| `credentials` | [`InteractionProcessCredentialRequest`](https://docs.maitento.com/reference/types/interaction-process-credential-request.md)`[] \| null` |  | Model keys for this run, in the order they are tried. Every interaction the app starts uses them before your tenant's model keys. Null or empty: only your tenant's keys are used. |
| `allowMaitentoFallback` | `boolean \| null` |  | Whether an interaction this app starts may use Maitento's own key for a provider once no key of yours for it is left. Null means no. |
| `credentialStack` | `string \| null` |  | The credential stack the run uses, by id or name, and every interaction and code pipeline it starts. Its credentials serve every model call, in the stack's order, and Maitento's own keys are never used. Leave it out to use the app's own stack, then the namespace's default, then your tenant's. Can't be combined with `credentials`. |
| `aiModelOverrides` | [`AiModelOverrideRequestInput`](https://docs.maitento.com/reference/types/ai-model-override-request.md#in-a-request)`[] \| null` |  | Model overrides for named agents, applied to every interaction this app starts. Null or empty: agents use the models their definitions name. |
| `webDownloadPartitionId` | `uuid \| null` |  | The temporary knowledge base (partition) that pages fetched by the web tools of every interaction and code pipeline this app starts are kept in, passed on to the apps it starts. Ignored unless it is one of your temporary knowledge bases. Null: each run uses its namespace's default, then the tenant's. |
| `webAccessOverrides` | [`WebAccessOverrideInput`](https://docs.maitento.com/reference/types/web-access-override.md#in-a-request)`[] \| null` |  | Web tool overrides (on or off, for all agents or one by name) applied to every interaction this app starts. |

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

```bash title="curl"
curl -X PUT "https://api.maitento.com/namespaces/<namespaceName>/apps/by-name/<name>/versions/latest/start" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"inputs":[]}'
```
```ts title="TypeScript"
const run = await mt.apps.start({ name: "refund-flow", namespace: "support" }, { inputs: { orderId: "A-1001" } });
```
```python title="Python"
mt.apps.start("triage", inputs={"ticket": "My invoice is wrong"}, namespace="demo")
```