# Builds (validate and deploy)

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

## `builds.list`

```http
GET /builds
```

The build history, newest first: await it for the first page, or iterate every build.

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

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `namespace` | `string[]` |  | Namespace names (exact, case-sensitive), repeatable or comma-separated: `?namespace=a&namespace=b` or `?namespace=a,b`. At most 50. Ignored when listing one namespace's builds. |
| `outcome` | `string` |  | Only builds that ended this way: `Succeeded`, `Failed` or `Rejected` (case-insensitive). |
| `isDeploy` | `boolean` |  | True: deploys only; false: validations only. Omitted: both. |
| `cursor` | `string` |  | The `nextCursor` of the previous page. |
| `limit` | `integer` |  | How many builds to return: 1 to 200, default 50. |

**Response:** [`BuildRecordPage`](https://docs.maitento.com/reference/types/build-record-page.md) (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/builds" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
for await (const build of mt.builds.list({ namespaces: ["demo", "support"], outcome: "Failed" })) console.log(build.id);
```
```python title="Python"
mt.builds.list(outcome="Failed")
```

## `builds.delete`

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

Deletes a build record (Tenant.Admin).

**Who can call it:** Tenant admins only, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=DELETE%20%2Fbuilds%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/builds/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
await mt.builds.delete("fdda765f-fc57-4604-a269-52a7df8164ec");
```
```python title="Python"
mt.builds.delete("2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d")
```

## `builds.get`

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

One build: manifest, sources, log, what it deployed. 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%2Fbuilds%2Fby-id%2F%7Bid%7D).

**Path parameters**

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

**Response:** [`BuildRecord`](https://docs.maitento.com/reference/types/build-record.md) (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/builds/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const build = await mt.builds.get("fdda765f-fc57-4604-a269-52a7df8164ec");
```
```python title="Python"
mt.builds.get("2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d")
```

## `builds.deploy`

```http
PUT /namespaces/{namespaceName}/build
```

Compiles and deploys the project into the namespace (creating the namespace if needed): each changed definition gets a new version. Throws `BuildFailedError` when the sources do not compile (nothing is deployed). 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%2Fbuild).

**Path parameters**

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

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

| Field | Type | Required | Description |
|---|---|---|---|
| `isDeploy` | `boolean` | yes | True to deploy the definitions if the build succeeds; false only to validate them. |
| `agents` | [`BuildRequestItem`](https://docs.maitento.com/reference/types/build-request-item.md)`[]` | yes | Agent files (`agents/`). |
| `capsules` | [`BuildRequestItem`](https://docs.maitento.com/reference/types/build-request-item.md)`[]` | yes | Capsule files (`capsules/`). |
| `connectors` | [`BuildOpenApiAndMcpRequest`](https://docs.maitento.com/reference/types/build-open-api-and-mcp-request.md) | yes | Connector files (`connectors/`). |
| `externalOperations` | [`BuildOpenApiAndMcpRequest`](https://docs.maitento.com/reference/types/build-open-api-and-mcp-request.md) | yes | Tool files (`external-operations/`). |
| `interactions` | [`BuildInteractionsRequest`](https://docs.maitento.com/reference/types/build-interactions-request.md) | yes | Interaction files (`interactions/`). |
| `apps` | [`BuildRequestApp`](https://docs.maitento.com/reference/types/build-request-app.md)`[]` | yes | Apps (`apps/`), one entry per app folder. |
| `codePipelines` | [`BuildRequestCodePipeline`](https://docs.maitento.com/reference/types/build-request-code-pipeline.md)`[]` | yes | Code pipeline definitions (`code-pipelines/`), sent as JSON. |
| `codePipelineHooks` | `map<string,`[`BuildRequestApp`](https://docs.maitento.com/reference/types/build-request-app.md)`> \| null` |  | Optional Cogniscript hooks for code pipelines (`code-pipeline-hooks/`), keyed by the pipeline's name. |
| `looms` | [`BuildRequestItem`](https://docs.maitento.com/reference/types/build-request-item.md)`[] \| null` |  | Optional named looms (`looms/<name>.mtr`). |
| `resourceFiles` | [`ResourceFileReferences`](https://docs.maitento.com/reference/types/resource-file-references.md) | yes | The shared prompts and JSON files the other files read with `@prompt` and `@json`. |

**Response:** [`BuildResponse`](https://docs.maitento.com/reference/types/build-response.md) (200)

```bash title="curl"
curl -X PUT "https://api.maitento.com/namespaces/<namespaceName>/build" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"isDeploy":false,"agents":[],"capsules":[],"connectors":{"openApi":[],"modelContextProtocol":[]},"externalOperations":{"openApi":[],"modelContextProtocol":[]},"interactions":{"oneShot":[],"roundRobin":[],"managed":[]},"apps":[],"codePipelines":[],"resourceFiles":{"prompts":[],"json":[]}}'
```
```ts title="TypeScript"
await mt.deploy("./maitento", { namespace: "support" }); // or mt.validate(...) / mt.builds.submit(request)
```
```python title="Python"
mt.deploy("./maitento", namespace="demo")
```

## `builds.list`

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

The build history, newest first: await it for the first page, or iterate every build.

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

**Path parameters**

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

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `namespace` | `string[]` |  | Namespace names (exact, case-sensitive), repeatable or comma-separated: `?namespace=a&namespace=b` or `?namespace=a,b`. At most 50. Ignored when listing one namespace's builds. |
| `outcome` | `string` |  | Only builds that ended this way: `Succeeded`, `Failed` or `Rejected` (case-insensitive). |
| `isDeploy` | `boolean` |  | True: deploys only; false: validations only. Omitted: both. |
| `cursor` | `string` |  | The `nextCursor` of the previous page. |
| `limit` | `integer` |  | How many builds to return: 1 to 200, default 50. |

**Response:** [`BuildRecordPage`](https://docs.maitento.com/reference/types/build-record-page.md) (200)

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