Files

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

`files.findByChecksum`

GET /files/by-checksum/{checksum}

The file with this content checksum, or null.

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
`checksum`	`string`	yes

Response: IngestedFileSummary (200)

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

const existing = await mt.files.findByChecksum("9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08");

mt.files.find_by_checksum("9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08")

`files.delete`

DELETE /files/by-id/{id}

Deletes a file (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/files/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH"

await mt.files.delete("52a1f6d8-3c7e-4b9a-8f2d-6e1c0b9a8d7f");

mt.files.delete("6d7e8f9a-0b1c-4d2e-8f3a-4b5c6d7e8f9a")

`files.download`

GET /files/by-id/{id}

The file’s original bytes, content type and file name.

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

Response: binary (200)

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

const { bytes, contentType } = await mt.files.download("52a1f6d8-3c7e-4b9a-8f2d-6e1c0b9a8d7f");

mt.files.download("6d7e8f9a-0b1c-4d2e-8f3a-4b5c6d7e8f9a")

`files.replace`

PATCH /files/by-id/{id}

Replaces a file’s content (the same content is a no-op). 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

Response: IngestedFile (200)

curl -X PATCH "https://api.maitento.com/files/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH" \
  -F "file=@handbook.pdf"

const file = await mt.files.replace("52a1f6d8-3c7e-4b9a-8f2d-6e1c0b9a8d7f", "./handbook-v2.pdf");

mt.files.replace("6d7e8f9a-0b1c-4d2e-8f3a-4b5c6d7e8f9a", "./handbook.pdf")

`files.get`

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

The file record (with its extracted text). 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

Query parameters

Name	Type	Required	Description
`partitionId`	`uuid`

Response: IngestedFile (200)

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

const file = await mt.files.get("52a1f6d8-3c7e-4b9a-8f2d-6e1c0b9a8d7f");

mt.files.get("6d7e8f9a-0b1c-4d2e-8f3a-4b5c6d7e8f9a")

`files.text`

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

The file’s extracted text.

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

Response: FileTextResponse (200)

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

const text = await mt.files.text("52a1f6d8-3c7e-4b9a-8f2d-6e1c0b9a8d7f");

mt.files.text("6d7e8f9a-0b1c-4d2e-8f3a-4b5c6d7e8f9a")

`files.search`

PUT /files/embeddings/search

Semantic search over a partition’s files.

Who can call it: Admins and members, with an API key or a portal session. Try it in the API playground.

Request body: EmbeddedVectorSearchRequest

Field	Type	Required	Description
`query`	`string`	yes	What to search for, in plain words.
`partitionId`	`uuid`	yes	The partition (knowledge base) to search.

Response: EmbeddingsSearchResult[] (200)

curl -X PUT "https://api.maitento.com/files/embeddings/search" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"query":"...","partitionId":"..."}'

const hits = await mt.files.search({ partitionId: "d6e5f4a3-b2c1-4d0e-9f8a-7b6c5d4e3f2a", query: "refund policy for damaged goods" });

mt.files.search("4b5c6d7e-8f9a-4b0c-9d1e-2f3a4b5c6d7e", "How many days of leave do I get?")

`files.upload`

PUT /files/partitions/{partitionId}

Uploads a file into a partition. Text extraction runs inside the call (it can take minutes: the default timeout is 6 minutes); chunking and embedding continue afterwards (ingested-file-updated, isVectorGenerated). The same bytes in the same partition are de-duplicated. 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
`partitionId`	`uuid`	yes

Response: IngestedFile (200)

curl -X PUT "https://api.maitento.com/files/partitions/<partitionId>" \
  -H "Authorization: $MAITENTO_AUTH" \
  -F "file=@handbook.pdf"

const file = await mt.files.upload("d6e5f4a3-b2c1-4d0e-9f8a-7b6c5d4e3f2a", "./handbook.pdf");

mt.files.upload("4b5c6d7e-8f9a-4b0c-9d1e-2f3a4b5c6d7e", "./handbook.pdf")