Repository Public
1---2title: Files3url: https://platform.claude.com/docs/en/api/files4---56# Files78## Upload File910**POST** `/v1/files`1112Upload File1314### Headers1516- `"anthropic-workspace-id": optional string`1718### Body parameters (form-data)1920- `file: string`2122 The file to upload. Only the final path component of the part's `filename` is kept; an absent or empty `filename` is replaced with `unnamed` plus the extension for the file's stored `mime_type`, when known.2324 format: binary2526- `expires_in_seconds: optional number`2728 Seconds from upload until the file expires and its bytes become permanently unavailable. Must be between 3600 (one hour) and 7776000 (ninety days).2930 minimum: 3600, maximum: 77760003132### Returns3334- `FileMetadata object`3536 - `type: "file"`3738 Object type.3940 For files, this is always `"file"`.4142 - `id: string`4344 Unique object identifier.4546 The format and length of IDs may change over time.4748 - `created_at: string`4950 RFC 3339 datetime string representing when the file was created.5152 format: date-time5354 - `filename: string`5556 Original filename of the uploaded file.5758 maxLength: 500, minLength: 15960 - `mime_type: string`6162 MIME type of the file.6364 maxLength: 255, minLength: 16566 - `size_bytes: number`6768 Size of the file in bytes.6970 minimum: 07172 - `downloadable: optional boolean`7374 Whether the file can be downloaded.7576 default: false7778 - `expires_at: optional string or null`7980 RFC 3339 datetime string representing when the file will expire and become unavailable for download. Null if the file does not expire. For files uploaded with `expires_in_seconds`, this is the upload time plus that value.8182 format: date-time8384### Example8586```bash87curl https://api.anthropic.com/v1/files \88 -H 'Content-Type: multipart/form-data' \89 -H 'anthropic-version: 2023-06-01' \90 -H "X-Api-Key: $ANTHROPIC_API_KEY" \91 -F 'file=@/path/to/file'92```9394#### Response (200)9596```json97{98 "id": "file_011CNha8iCJcU1wXNR6q4V8w",99 "created_at": "2025-04-15T18:37:24.100435Z",100 "filename": "document.pdf",101 "mime_type": "application/pdf",102 "size_bytes": 102400,103 "type": "file",104 "downloadable": false,105 "expires_at": "2025-05-15T18:37:24.100435Z"106}107```108109## List Files110111**GET** `/v1/files`112113List Files114115### Query parameters116117- `ids: optional array of string`118119 Restrict the result set to Files whose `id` is in this list. At most 100 entries (after de-duplication). Mutually exclusive with `page` and `limit`. When supplied, the response is always a single page (`next_page` is null). IDs that do not resolve to a visible File — including deleted Files — are silently omitted.120121- `limit: optional number`122123 Number of items to return per page.124125 Defaults to `20`. Ranges from `1` to `1000`.126127 default: 20, maximum: 1000, minimum: 1128129- `page: optional string`130131 Opaque page cursor returned in a prior list response's `next_page`. Prefixed `page_`.132133### Headers134135- `"anthropic-workspace-id": optional string`136137### Returns138139- `data: array of FileMetadata`140141 List of file metadata objects.142143 - `type: "file"`144145 Object type.146147 For files, this is always `"file"`.148149 - `id: string`150151 Unique object identifier.152153 The format and length of IDs may change over time.154155 - `created_at: string`156157 RFC 3339 datetime string representing when the file was created.158159 format: date-time160161 - `filename: string`162163 Original filename of the uploaded file.164165 maxLength: 500, minLength: 1166167 - `mime_type: string`168169 MIME type of the file.170171 maxLength: 255, minLength: 1172173 - `size_bytes: number`174175 Size of the file in bytes.176177 minimum: 0178179 - `downloadable: optional boolean`180181 Whether the file can be downloaded.182183 default: false184185 - `expires_at: optional string or null`186187 RFC 3339 datetime string representing when the file will expire and become unavailable for download. Null if the file does not expire. For files uploaded with `expires_in_seconds`, this is the upload time plus that value.188189 format: date-time190191- `next_page: optional string or null`192193 Opaque cursor for the next page. Supply as `?page=` to fetch the next page; null when there are no more results.194195### Example196197```bash198curl https://api.anthropic.com/v1/files \199 -H 'anthropic-version: 2023-06-01' \200 -H "X-Api-Key: $ANTHROPIC_API_KEY"201```202203#### Response (200)204205```json206{207 "data": [208 {209 "id": "file_011CNha8iCJcU1wXNR6q4V8w",210 "created_at": "2025-04-15T18:37:24.100435Z",211 "filename": "document.pdf",212 "mime_type": "application/pdf",213 "size_bytes": 102400,214 "type": "file",215 "downloadable": false,216 "expires_at": "2025-05-15T18:37:24.100435Z"217 }218 ],219 "next_page": "next_page"220}221```222223## Download File224225**GET** `/v1/files/{file_id}/content`226227Download File228229### Path parameters230231- `file_id: string`232233 ID of the File.234235### Headers236237- `"anthropic-workspace-id": optional string`238239### Example240241```bash242curl https://api.anthropic.com/v1/files/$FILE_ID/content \243 -H 'anthropic-version: 2023-06-01' \244 -H "X-Api-Key: $ANTHROPIC_API_KEY"245```246247## Get File Metadata248249**GET** `/v1/files/{file_id}`250251Get File Metadata252253### Path parameters254255- `file_id: string`256257 ID of the File.258259### Headers260261- `"anthropic-workspace-id": optional string`262263### Returns264265- `FileMetadata object`266267 - `type: "file"`268269 Object type.270271 For files, this is always `"file"`.272273 - `id: string`274275 Unique object identifier.276277 The format and length of IDs may change over time.278279 - `created_at: string`280281 RFC 3339 datetime string representing when the file was created.282283 format: date-time284285 - `filename: string`286287 Original filename of the uploaded file.288289 maxLength: 500, minLength: 1290291 - `mime_type: string`292293 MIME type of the file.294295 maxLength: 255, minLength: 1296297 - `size_bytes: number`298299 Size of the file in bytes.300301 minimum: 0302303 - `downloadable: optional boolean`304305 Whether the file can be downloaded.306307 default: false308309 - `expires_at: optional string or null`310311 RFC 3339 datetime string representing when the file will expire and become unavailable for download. Null if the file does not expire. For files uploaded with `expires_in_seconds`, this is the upload time plus that value.312313 format: date-time314315### Example316317```bash318curl https://api.anthropic.com/v1/files/$FILE_ID \319 -H 'anthropic-version: 2023-06-01' \320 -H "X-Api-Key: $ANTHROPIC_API_KEY"321```322323#### Response (200)324325```json326{327 "id": "file_011CNha8iCJcU1wXNR6q4V8w",328 "created_at": "2025-04-15T18:37:24.100435Z",329 "filename": "document.pdf",330 "mime_type": "application/pdf",331 "size_bytes": 102400,332 "type": "file",333 "downloadable": false,334 "expires_at": "2025-05-15T18:37:24.100435Z"335}336```337338## Delete File339340**DELETE** `/v1/files/{file_id}`341342Delete File343344### Path parameters345346- `file_id: string`347348 ID of the File.349350### Headers351352- `"anthropic-workspace-id": optional string`353354### Returns355356- `DeletedFile object`357358 - `type: optional "file_deleted"`359360 Deleted object type.361362 For file deletion, this is always `"file_deleted"`.363364 default: file_deleted365366 - `id: string`367368 ID of the deleted file.369370### Example371372```bash373curl https://api.anthropic.com/v1/files/$FILE_ID \374 -X DELETE \375 -H 'anthropic-version: 2023-06-01' \376 -H "X-Api-Key: $ANTHROPIC_API_KEY"377```378379#### Response (200)380381```json382{383 "id": "file_011CNha8iCJcU1wXNR6q4V8w",384 "type": "file_deleted"385}386```387388## Domain types389390### Deleted File391392- `DeletedFile object`393394 - `type: optional "file_deleted"`395396 Deleted object type.397398 For file deletion, this is always `"file_deleted"`.399400 default: file_deleted401402 - `id: string`403404 ID of the deleted file.405406### File Metadata407408- `FileMetadata object`409410 - `type: "file"`411412 Object type.413414 For files, this is always `"file"`.415416 - `id: string`417418 Unique object identifier.419420 The format and length of IDs may change over time.421422 - `created_at: string`423424 RFC 3339 datetime string representing when the file was created.425426 format: date-time427428 - `filename: string`429430 Original filename of the uploaded file.431432 maxLength: 500, minLength: 1433434 - `mime_type: string`435436 MIME type of the file.437438 maxLength: 255, minLength: 1439440 - `size_bytes: number`441442 Size of the file in bytes.443444 minimum: 0445446 - `downloadable: optional boolean`447448 Whether the file can be downloaded.449450 default: false451452 - `expires_at: optional string or null`453454 RFC 3339 datetime string representing when the file will expire and become unavailable for download. Null if the file does not expire. For files uploaded with `expires_in_seconds`, this is the upload time plus that value.455456 format: date-time457