# File reads and location objects

Times are Unix seconds; size is in bytes. Metadata describes the file itself, while an association location describes its reference within a volume. Zero-valued scalars may be omitted. Source conversation/task/call/tool information is read back according to current identity visibility.

(metadata)=
## Workspace file metadata

| Field | Type | Description |
| --- | --- | --- |
| `file_id` | string | File ID. |
| `original_name` | string | Original file name. |
| `md5` | string | Content digest. |
| `size` | integer | File size in bytes. |
| `ref_count` | integer | Current reference count. |
| `created_at` | integer | Creation time in Unix seconds. |
| `created_by` | string | Creator ID. |
| `updated_at` | integer | Update time in Unix seconds. |
| `source` | string | Source category. |
| `source_session_id` | string | Source conversation ID, returned according to visibility. |
| `source_task_id` | string | Source task ID, returned according to visibility. |
| `source_call_id` | string | Source call ID, returned according to visibility. |
| `content_type` | string | Saved content type. |
| `source_tool` | string | Source tool identifier, returned according to visibility. |
| `storage_mode` | string | Storage mode. |
| `external_connector_id` | string | External connector ID, when applicable. |
| `external_uri` | string | External object URI, when applicable. |

(placement)=
## Volume file association location

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer | Volume file association record ID. |
| `volume_id` | integer | Associated volume ID. |
| `file_id` | string | File ID. |
| `file_name` | string | File name at this location. |
| `file_path` | string | Relative path within the volume. |
| `created_at` | integer | Creation time in Unix seconds. |
| `created_by` | string | Creator ID. |
| `updated_at` | integer | Update time in Unix seconds. |
| `updated_by` | string | Updater ID. |
| `original_name` | string | Original file name. |
| `md5` | string | Content digest. |
| `size` | integer | File size in bytes. |
| `ref_count` | integer | Current reference count. |
| `revision` | integer | Association location revision. |
| `source` | string | Source category. |
| `source_session_id` | string | Source conversation ID, returned according to visibility. |
| `source_task_id` | string | Source task ID, returned according to visibility. |
| `source_call_id` | string | Source call ID, returned according to visibility. |
| `content_type` | string | Saved content type. |
| `source_tool` | string | Source tool identifier, returned according to visibility. |
| `sandbox_path` | string | Sandbox mount path. |

(private-location)=
## Private volume upload location

| Field | Type | Description |
| --- | --- | --- |
| `workspace_id` | string | Workspace ID. |
| `volume_id` | integer | Associated volume ID. |
| `file_id` | string | File ID. |
| `path` | string | Path within the volume. |
| `name` | string | Association name. |
| `size` | integer | File size in bytes. |
| `md5` | string | Content digest. |
