Builds (validate and deploy)

5 calls. Every request needs the Authorization header: see the overview.

`builds.list`

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.

Query parameters

Name	Type	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 (200)

curl -X GET "https://api.maitento.com/builds" \
  -H "Authorization: $MAITENTO_AUTH"

for await (const build of mt.builds.list({ namespaces: ["demo", "support"], outcome: "Failed" })) console.log(build.id);

mt.builds.list(outcome="Failed")

`builds.delete`

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.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Response: no body (204)

curl -X DELETE "https://api.maitento.com/builds/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH"

await mt.builds.delete("fdda765f-fc57-4604-a269-52a7df8164ec");

mt.builds.delete("2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d")

`builds.get`

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.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Response: BuildRecord (200)

curl -X GET "https://api.maitento.com/builds/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH"

const build = await mt.builds.get("fdda765f-fc57-4604-a269-52a7df8164ec");

mt.builds.get("2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d")

`builds.deploy`

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.

Path parameters

Name	Type	Required	Description
`namespaceName`	`string`	yes

Request body: BuildRequest

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

Response: BuildResponse (200)

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":[]}}'

await mt.deploy("./maitento", { namespace: "support" }); // or mt.validate(...) / mt.builds.submit(request)

mt.deploy("./maitento", namespace="demo")

`builds.list`

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.

Path parameters

Name	Type	Required	Description
`namespaceName`	`string`	yes

Query parameters

Name	Type	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 (200)

curl -X GET "https://api.maitento.com/namespaces/<namespaceName>/builds" \
  -H "Authorization: $MAITENTO_AUTH"

const page = await mt.builds.list({ namespace: "support", limit: 20 });

mt.builds.list(namespace="demo", is_deploy=True)