# IngestedFile

A file uploaded to a partition (or downloaded into one by an agent's web tools): its extracted text, and how far it has got through being described, chunked and embedded for search.

**Kind:** an object, used in responses.

## Fields

Every field is present in a response; empty ones are `null`.

| Field | Type | Description |
|---|---|---|
| `name` | `string` | The file's name. |
| `contentType` | `string` | The file's MIME type, such as `application/pdf`. |
| `size` | `integer` | The file's size, in bytes. |
| `type` | [`IngestedFileType`](https://docs.maitento.com/reference/types/ingested-file-type.md) | What kind of document it is, which decides how its text is extracted. |
| `text` | `string` | The text extracted from the file. |
| `isImageDescriptionRequired` | `boolean` | True while an image is waiting to be described in words, so it can be searched. |
| `imageDescriptionTime` | `datetime \| null` | When the image was described (UTC). Null for other files, and until it has been. |
| `isTrainingDataGenerated` | `boolean` | Not used: always false. |
| `trainingDataTime` | `datetime \| null` | Not used: always null. |
| `isVectorGenerated` | `boolean` | True once the file has been embedded and can be found by search. |
| `vectorGenerationTime` | `datetime \| null` | When the file was last embedded (UTC). Null until it has been. |
| `indexingFailure` | [`IngestedFileIndexingFailure`](https://docs.maitento.com/reference/types/ingested-file-indexing-failure.md)`\| null` | Why the file cannot be indexed until someone acts, such as no embedding key for its knowledge base. Null while it is being indexed, once it is, and when its content changes. Search of a knowledge base that cannot embed is refused with the same code. |
| `embeddingModelKey` | `string \| null` | The provider, model and width (`provider/model@width`) the file's current embedding was made with. Null until it is embedded. While a partition is re-indexed, a file counts as done once this matches the partition's new profile. |
| `isChunkingRequired` | `boolean` | True while the file is waiting to be split into chunks before it is embedded. False once it has been, and for a file short enough to be embedded whole. |
| `chunkGenerationTime` | `datetime \| null` | When the file was split into chunks (UTC). Null until it has been, or if it did not need to be. |
| `partitionId` | `uuid` | The partition the file belongs to. |
| `isTemporary` | `boolean` | True for a file in a temporary partition: it is never indexed or searchable, raises no webhooks, and is removed once `expiresAt` has passed. False on every file of an ordinary partition. |
| `expiresAt` | `datetime \| null` | When a temporary file is removed (UTC). Null on every file of an ordinary partition. |
| `webSource` | [`IngestedFileWebSource`](https://docs.maitento.com/reference/types/ingested-file-web-source.md)`\| null` | Where a web download came from. Null on every uploaded file. |
| `version` | `integer` | The file's version: 1 on upload, and one more each time its content is replaced with something different. |
| `userCreatedById` | `uuid` | The id of the user who created it. A call made with an API key is recorded as the key's user. |
| `tenantId` | `uuid` | The id of the tenant it belongs to. |
| `id` | `uuid` | The unique id. Use it in `by-id` routes and wherever another object refers to this one. |
| `dateCreated` | `datetime` | When it was created, in UTC. |
| `dateUpdated` | `datetime` | When it was last changed, in UTC. |

## Example

```json
{
  "name": "...",
  "contentType": "...",
  "size": 0,
  "type": "WordDocument",
  "text": "...",
  "isImageDescriptionRequired": false,
  "imageDescriptionTime": "2026-10-26T12:00:00.0000000Z",
  "isTrainingDataGenerated": false,
  "trainingDataTime": "2026-10-26T12:00:00.0000000Z",
  "isVectorGenerated": false,
  "vectorGenerationTime": "2026-10-26T12:00:00.0000000Z",
  "indexingFailure": {
    "code": "...",
    "message": "...",
    "dateFailed": "2026-10-26T12:00:00.0000000Z"
  },
  "embeddingModelKey": "...",
  "isChunkingRequired": false,
  "chunkGenerationTime": "2026-10-26T12:00:00.0000000Z",
  "partitionId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "isTemporary": false,
  "expiresAt": "2026-10-26T12:00:00.0000000Z",
  "webSource": {
    "url": "...",
    "finalUrl": "...",
    "title": "...",
    "kind": "Page",
    "route": "Datacenter",
    "processType": "App",
    "processId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
    "agentName": "...",
    "isTextCapped": false
  },
  "version": 0,
  "userCreatedById": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "tenantId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "id": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "dateCreated": "2026-10-26T12:00:00.0000000Z",
  "dateUpdated": "2026-10-26T12:00:00.0000000Z"
}
```

## Where it's used

- [`files.get`](https://docs.maitento.com/reference/api/files.md) (`GET /files/by-id/{id}/details`)
- [`files.replace`](https://docs.maitento.com/reference/api/files.md) (`PATCH /files/by-id/{id}`)
- [`files.upload`](https://docs.maitento.com/reference/api/files.md) (`PUT /files/partitions/{partitionId}`)