# Files

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

## `files.findByChecksum`

```http
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](https://docs.maitento.com/playground/?call=GET%20%2Ffiles%2Fby-checksum%2F%7Bchecksum%7D).

**Path parameters**

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

**Response:** [`IngestedFileSummary`](https://docs.maitento.com/reference/types/ingested-file-summary.md) (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/files/by-checksum/<checksum>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const existing = await mt.files.findByChecksum("9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08");
```
```python title="Python"
mt.files.find_by_checksum("9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08")
```

## `files.delete`

```http
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](https://docs.maitento.com/playground/?call=DELETE%20%2Ffiles%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/files/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
await mt.files.delete("52a1f6d8-3c7e-4b9a-8f2d-6e1c0b9a8d7f");
```
```python title="Python"
mt.files.delete("6d7e8f9a-0b1c-4d2e-8f3a-4b5c6d7e8f9a")
```

## `files.download`

```http
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](https://docs.maitento.com/playground/?call=GET%20%2Ffiles%2Fby-id%2F%7Bid%7D).

**Path parameters**

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

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `partitionId` | `uuid` |  |  |

**Response:** `binary` (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/files/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const { bytes, contentType } = await mt.files.download("52a1f6d8-3c7e-4b9a-8f2d-6e1c0b9a8d7f");
```
```python title="Python"
mt.files.download("6d7e8f9a-0b1c-4d2e-8f3a-4b5c6d7e8f9a")
```

## `files.replace`

```http
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](https://docs.maitento.com/playground/?call=PATCH%20%2Ffiles%2Fby-id%2F%7Bid%7D).

**Path parameters**

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

**Response:** [`IngestedFile`](https://docs.maitento.com/reference/types/ingested-file.md) (200)

```bash title="curl"
curl -X PATCH "https://api.maitento.com/files/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH" \
  -F "file=@handbook.pdf"
```
```ts title="TypeScript"
const file = await mt.files.replace("52a1f6d8-3c7e-4b9a-8f2d-6e1c0b9a8d7f", "./handbook-v2.pdf");
```
```python title="Python"
mt.files.replace("6d7e8f9a-0b1c-4d2e-8f3a-4b5c6d7e8f9a", "./handbook.pdf")
```

## `files.get`

```http
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](https://docs.maitento.com/playground/?call=GET%20%2Ffiles%2Fby-id%2F%7Bid%7D%2Fdetails).

**Path parameters**

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

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `partitionId` | `uuid` |  |  |

**Response:** [`IngestedFile`](https://docs.maitento.com/reference/types/ingested-file.md) (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/files/by-id/<id>/details" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const file = await mt.files.get("52a1f6d8-3c7e-4b9a-8f2d-6e1c0b9a8d7f");
```
```python title="Python"
mt.files.get("6d7e8f9a-0b1c-4d2e-8f3a-4b5c6d7e8f9a")
```

## `files.text`

```http
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](https://docs.maitento.com/playground/?call=GET%20%2Ffiles%2Fby-id%2F%7Bid%7D%2Ftext).

**Path parameters**

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

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `partitionId` | `uuid` |  |  |

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

```bash title="curl"
curl -X GET "https://api.maitento.com/files/by-id/<id>/text" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const text = await mt.files.text("52a1f6d8-3c7e-4b9a-8f2d-6e1c0b9a8d7f");
```
```python title="Python"
mt.files.text("6d7e8f9a-0b1c-4d2e-8f3a-4b5c6d7e8f9a")
```

## `files.search`

```http
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](https://docs.maitento.com/playground/?call=PUT%20%2Ffiles%2Fembeddings%2Fsearch).

**Request body:** [`EmbeddedVectorSearchRequest`](https://docs.maitento.com/reference/types/embedded-vector-search-request.md)

| 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`](https://docs.maitento.com/reference/types/embeddings-search-result.md)`[]` (200)

```bash title="curl"
curl -X PUT "https://api.maitento.com/files/embeddings/search" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"query":"...","partitionId":"..."}'
```
```ts title="TypeScript"
const hits = await mt.files.search({ partitionId: "d6e5f4a3-b2c1-4d0e-9f8a-7b6c5d4e3f2a", query: "refund policy for damaged goods" });
```
```python title="Python"
mt.files.search("4b5c6d7e-8f9a-4b0c-9d1e-2f3a4b5c6d7e", "How many days of leave do I get?")
```

## `files.upload`

```http
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](https://docs.maitento.com/playground/?call=PUT%20%2Ffiles%2Fpartitions%2F%7BpartitionId%7D).

**Path parameters**

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

**Response:** [`IngestedFile`](https://docs.maitento.com/reference/types/ingested-file.md) (200)

```bash title="curl"
curl -X PUT "https://api.maitento.com/files/partitions/<partitionId>" \
  -H "Authorization: $MAITENTO_AUTH" \
  -F "file=@handbook.pdf"
```
```ts title="TypeScript"
const file = await mt.files.upload("d6e5f4a3-b2c1-4d0e-9f8a-7b6c5d4e3f2a", "./handbook.pdf");
```
```python title="Python"
mt.files.upload("4b5c6d7e-8f9a-4b0c-9d1e-2f3a4b5c6d7e", "./handbook.pdf")
```