Knowledge bases (partitions)

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

`partitions.list`

GET /partitions

Every partition.

Who can call it: Tenant admins only, with an API key or a portal session. Try it in the API playground.

Response: Partition[] (200)

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

const partitions = await mt.partitions.list();

mt.partitions.list()

`partitions.create`

PUT /partitions

Creates a partition (a temporary one deletes its files after fileLifetimeHours).

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
`partitionId`	`uuid`	yes

Request body: PartitionCreateRequest

Field	Type	Required	Description
`name`	`string`	yes	The partition’s name.
`isTemporary`	`boolean`		Create a temporary partition: its files are never indexed and are removed once they are `fileLifetimeHours` old. Cannot be changed once the partition exists.
`fileLifetimeHours`	`integer \| null`		A temporary partition’s file lifetime, in hours; null is 24. Refused on an ordinary partition.

Response: Partition (200)

curl -X PUT "https://api.maitento.com/partitions" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"name":"..."}'

const partition = await mt.partitions.create({ name: "handbooks" });

mt.partitions.create("handbook")

`partitions.delete`

DELETE /partitions/by-id/{id}

Deletes an empty partition (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/partitions/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH"

await mt.partitions.delete("d6e5f4a3-b2c1-4d0e-9f8a-7b6c5d4e3f2a");

mt.partitions.delete("4b5c6d7e-8f9a-4b0c-9d1e-2f3a4b5c6d7e")

`partitions.get`

GET /partitions/by-id/{id}

The partition with this id. Throws NotFoundError when there is none.

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: Partition (200)

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

const partition = await mt.partitions.get("d6e5f4a3-b2c1-4d0e-9f8a-7b6c5d4e3f2a");

mt.partitions.get("4b5c6d7e-8f9a-4b0c-9d1e-2f3a4b5c6d7e")

`partitions.acknowledgeEmbeddingCredentialFailures`

PUT /partitions/by-id/{id}/embedding-credential-failures/acknowledge

Marks a partition’s embedding-credential failures as seen.

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 PUT "https://api.maitento.com/partitions/by-id/<id>/embedding-credential-failures/acknowledge" \
  -H "Authorization: $MAITENTO_AUTH"

await mt.partitions.acknowledgeEmbeddingCredentialFailures("d6e5f4a3-b2c1-4d0e-9f8a-7b6c5d4e3f2a");

mt.partitions.acknowledge_embedding_credential_failures("4b5c6d7e-8f9a-4b0c-9d1e-2f3a4b5c6d7e")

`partitions.setEmbeddingCredentialStack`

PUT /partitions/by-id/{id}/embedding-credential-stack

Sets the credential stack a partition embeds with (Tenant.Admin), or clears it with null. Its own embedding keys are tried first, then the stack’s, in place of the tenant’s model keys and default stack; Maitento’s key is never used.

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

Request body: PartitionEmbeddingCredentialStackRequest

Field	Type	Required	Description
`credentialStackId`	`uuid \| null`		The id of one of your credential stacks, or null to clear.

Response: Partition (200)

curl -X PUT "https://api.maitento.com/partitions/by-id/<id>/embedding-credential-stack" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"credentialStackId":"..."}'

await mt.partitions.setEmbeddingCredentialStack("d6e5f4a3-b2c1-4d0e-9f8a-7b6c5d4e3f2a", "5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f"); // null clears it

mt.partitions.set_embedding_credential_stack("4b5c6d7e-8f9a-4b0c-9d1e-2f3a4b5c6d7e", "5a6b7c8d-9e0f-4a1b-8c2d-e3f4a5b6c7d8")

`partitions.clearEmbeddingCredentials`

DELETE /partitions/by-id/{id}/embedding-credentials

Removes a partition’s embedding keys.

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/partitions/by-id/<id>/embedding-credentials" \
  -H "Authorization: $MAITENTO_AUTH"

await mt.partitions.clearEmbeddingCredentials("d6e5f4a3-b2c1-4d0e-9f8a-7b6c5d4e3f2a");

mt.partitions.clear_embedding_credentials("4b5c6d7e-8f9a-4b0c-9d1e-2f3a4b5c6d7e")

`partitions.setEmbeddingCredentials`

PUT /partitions/by-id/{id}/embedding-credentials

Sets the keys a partition embeds with (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

Request body: PartitionEmbeddingCredentialsRequest

Field	Type	Required	Description
`credentials`	`PartitionEmbeddingCredentialInput[]`	yes	The keys, in failover order. May be empty only with `allowMaitentoFallback` true, which means “no key of my own, use Maitento’s”. To remove the keys, use `DELETE /partitions/by-id/{id}/embedding-credentials`.
`allowMaitentoFallback`	`boolean`		Consent to fall back to Maitento’s key when every key above has failed. Defaults to false: once your own keys are exhausted, the embedding fails.

Response: Partition (200)

curl -X PUT "https://api.maitento.com/partitions/by-id/<id>/embedding-credentials" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"credentials":[]}'

await mt.partitions.setEmbeddingCredentials("d6e5f4a3-b2c1-4d0e-9f8a-7b6c5d4e3f2a", { credentials, allowMaitentoFallback: false });

mt.partitions.set_embedding_credentials("4b5c6d7e-8f9a-4b0c-9d1e-2f3a4b5c6d7e", credentials=[{"provider": "OpenAi", "apiKey": os.environ["OPENAI_API_KEY"]}], allow_maitento_fallback=False)

`partitions.changeEmbeddingProfile`

PUT /partitions/by-id/{id}/embedding-profile

Changes a partition’s embedding profile (may re-index every file: never retried).

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

Request body: PartitionEmbeddingProfileRequest

Field	Type	Required	Description
`profile`	`PartitionEmbeddingProfileInput`	yes	The profile to index the partition with.
`credentials`	`PartitionEmbeddingCredentialInput[]`	yes	Your keys for the profile’s provider, in failover order. May be empty only with `allowMaitentoFallback` true, which means “no key of my own, use Maitento’s”, or with a `credentialStackId`.
`allowMaitentoFallback`	`boolean`		Consent to fall back to Maitento’s key for this provider when your keys are exhausted.
`credentialStackId`	`uuid \| null`		The id of one of your credential stacks for the partition to embed with, set in the same change, so the profile and the stack that serves it always match. With a stack, `credentials` may be empty, and Maitento’s key is never used. Null leaves the partition’s stack as it is; clear one with `PUT /partitions/by-id/{id}/embedding-credential-stack`.
`allowReindex`	`boolean`		Whether this request may start a re-index. Defaults to true. Send false when you only mean to update the keys: if the profile would need a different index, the request is refused with `api:embeddings:reindex-not-permitted` and nothing changes. When the profile needs the same index, a failed re-index is resumed if the keys or consent changed, or, when this is true, even if they did not (a deliberate retry).

Response: Partition (200)

curl -X PUT "https://api.maitento.com/partitions/by-id/<id>/embedding-profile" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"profile":{"model":"..."},"credentials":[]}'

await mt.partitions.changeEmbeddingProfile("d6e5f4a3-b2c1-4d0e-9f8a-7b6c5d4e3f2a", { profile, credentials, allowMaitentoFallback: false, allowReindex: true });

mt.partitions.change_embedding_profile("4b5c6d7e-8f9a-4b0c-9d1e-2f3a4b5c6d7e", profile={"provider": "OpenAi", "model": "text-embedding-3-large"}, allow_reindex=True)

`partitions.files`

GET /partitions/by-id/{id}/files

The partition’s files, newest first: await it for the first page, or iterate every file.

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

Query parameters

Name	Type	Required	Description
`cursor`	`string`
`limit`	`integer`

Response: IngestedFilePage (200)

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

for await (const file of mt.partitions.files("d6e5f4a3-b2c1-4d0e-9f8a-7b6c5d4e3f2a")) console.log(file.name);

mt.partitions.files("4b5c6d7e-8f9a-4b0c-9d1e-2f3a4b5c6d7e", limit=100)

`partitions.listEmbeddingCredentialFailures`

GET /partitions/embedding-credential-failures

Partitions whose embedding credentials failed (Tenant.Admin).

Who can call it: Tenant admins only, with an API key or a portal session. Try it in the API playground.

Response: Partition[] (200)

curl -X GET "https://api.maitento.com/partitions/embedding-credential-failures" \
  -H "Authorization: $MAITENTO_AUTH"

const failing = await mt.partitions.listEmbeddingCredentialFailures();

mt.partitions.list_embedding_credential_failures()

`partitions.embeddingModels`

GET /partitions/embedding-models

The embedding models a partition can use.

Who can call it: Tenant admins only, with an API key or a portal session. Try it in the API playground.

Response: EmbeddingModelDefinition[] (200)

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

const embeddingModels = await mt.partitions.embeddingModels();

mt.partitions.embedding_models()

`partitions.probeEmbeddingProfile`

POST /partitions/embedding-profile/probe

Tries an embedding profile and keys without saving them (a failed probe is still a 200).

Who can call it: Tenant admins only, with an API key or a portal session. Try it in the API playground.

Request body: PartitionEmbeddingProbeRequest

Field	Type	Required	Description
`profile`	`PartitionEmbeddingProfileInput`	yes	The profile to test, validated exactly as a profile change is (a custom model must state its width).
`credentials`	`PartitionEmbeddingCredentialInput[]`		The keys to test with, in priority order. At least one; the same rules apply as when setting a partition’s keys.

Response: PartitionEmbeddingProbeResult (200)

curl -X POST "https://api.maitento.com/partitions/embedding-profile/probe" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"profile":{"model":"..."}}'

const probe = await mt.partitions.probeEmbeddingProfile({ profile, credentials });

mt.partitions.probe_embedding_profile(profile={"provider": "OpenAi", "model": "text-embedding-3-large"})

`partitions.embeddingStatus`

PUT /partitions/embedding-status

The embedding status of many partitions (sent in batches of 500 ids).

Who can call it: Tenant admins only, with an API key or a portal session. Try it in the API playground.

Request body: PartitionEmbeddingStatusRequest

Field	Type	Required	Description
`partitionIds`	`uuid[]`	yes	The partitions to report on. Unknown ids (or another tenant’s) are omitted from the response.

Response: PartitionEmbeddingStatus[] (200)

curl -X PUT "https://api.maitento.com/partitions/embedding-status" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"partitionIds":[]}'

const statuses = await mt.partitions.embeddingStatus({ partitionIds: ["d6e5f4a3-b2c1-4d0e-9f8a-7b6c5d4e3f2a"] });

mt.partitions.embedding_status(["4b5c6d7e-8f9a-4b0c-9d1e-2f3a4b5c6d7e"])