Repository Public
1---2title: Files3url: https://platform.claude.com/docs/en/api/beta/files4---56# Files78## Upload File910**POST** `/v1/files`1112Upload File1314### Headers1516- `"anthropic-beta": optional array of AnthropicBeta`1718 Optional header to specify the beta version(s) you want to use.1920 - `string`2122 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more`2324 - `"message-batches-2024-09-24"`2526 - `"prompt-caching-2024-07-31"`2728 - `"computer-use-2024-10-22"`2930 - `"computer-use-2025-01-24"`3132 - `"pdfs-2024-09-25"`3334 - `"token-counting-2024-11-01"`3536 - `"token-efficient-tools-2025-02-19"`3738 - `"output-128k-2025-02-19"`3940 - `"files-api-2025-04-14"`4142 - `"mcp-client-2025-04-04"`4344 - `"mcp-client-2025-11-20"`4546 - `"dev-full-thinking-2025-05-14"`4748 - `"interleaved-thinking-2025-05-14"`4950 - `"code-execution-2025-05-22"`5152 - `"extended-cache-ttl-2025-04-11"`5354 - `"context-1m-2025-08-07"`5556 - `"context-management-2025-06-27"`5758 - `"model-context-window-exceeded-2025-08-26"`5960 - `"skills-2025-10-02"`6162 - `"fast-mode-2026-02-01"`6364 - `"output-300k-2026-03-24"`6566 - `"user-profiles-2026-03-24"`6768 - `"user-profiles-2026-08-18"`6970 - `"user-profiles-2026-09-04"`7172 - `"advisor-tool-2026-03-01"`7374 - `"managed-agents-2026-04-01"`7576 - `"cache-diagnosis-2026-04-07"`7778 - `"dreaming-2026-04-21"`7980 - `"thinking-token-count-2026-05-13"`8182 - `"server-side-fallback-2026-06-01"`8384 - `"server-side-fallback-2026-07-01"`8586 - `"fallback-credit-2026-06-01"`8788 - `"fallback-credit-2026-07-01"`8990 - `"agent-memory-2026-07-22"`9192 - `"mid-conversation-tool-changes-2026-07-01"`9394 - `"compact-2026-01-12"`9596 - `"computer-use-2025-11-24"`9798 - `"mcp-tunnels-2026-06-22"`99100 - `"structured-outputs-2025-11-13"`101102 - `"task-budgets-2026-03-13"`103104 - `"thinking-display-updates-2026-08-18"`105106 - `"ce-user-management-2026-07-13"`107108 - `"mid-conversation-output-config-2026-07-01"`109110 - `"thinking-binding-controls-2026-08-01"`111112 - `"mid-conversation-system-clear-at-2026-08-21"`113114 - `"compact-2026-09-04"`115116- `"anthropic-workspace-id": optional string`117118### Body parameters (form-data)119120- `file: string`121122 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.123124 format: binary125126- `expires_in_seconds: optional number`127128 Seconds from upload until the file expires and its bytes become permanently unavailable. Must be between 3600 (one hour) and 7776000 (ninety days).129130 minimum: 3600, maximum: 7776000131132### Returns133134- `BetaFileMetadata object`135136 - `type: "file"`137138 Object type.139140 For files, this is always `"file"`.141142 - `id: string`143144 Unique object identifier.145146 The format and length of IDs may change over time.147148 - `created_at: string`149150 RFC 3339 datetime string representing when the file was created.151152 format: date-time153154 - `filename: string`155156 Original filename of the uploaded file.157158 maxLength: 500, minLength: 1159160 - `mime_type: string`161162 MIME type of the file.163164 maxLength: 255, minLength: 1165166 - `size_bytes: number`167168 Size of the file in bytes.169170 minimum: 0171172 - `downloadable: optional boolean`173174 Whether the file can be downloaded.175176 default: false177178 - `expires_at: optional string or null`179180 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.181182 format: date-time183184 - `scope: optional BetaFileScope or null`185186 The scope of this file, indicating the context in which it was created (e.g., a session).187188 - `type: "session"`189190 The type of scope (e.g., `"session"`).191192 - `id: string`193194 The ID of the scoping resource (e.g., the session ID).195196### Example197198```bash199curl https://api.anthropic.com/v1/files \200 -H 'Content-Type: multipart/form-data' \201 -H 'anthropic-version: 2023-06-01' \202 -H "X-Api-Key: $ANTHROPIC_API_KEY" \203 -F 'file=@/path/to/file'204```205206#### Response (200)207208```json209{210 "id": "file_011CNha8iCJcU1wXNR6q4V8w",211 "created_at": "2025-04-15T18:37:24.100435Z",212 "filename": "document.pdf",213 "mime_type": "application/pdf",214 "size_bytes": 102400,215 "type": "file",216 "downloadable": false,217 "expires_at": "2025-05-15T18:37:24.100435Z",218 "scope": {219 "id": "id",220 "type": "session"221 }222}223```224225## List Files226227**GET** `/v1/files`228229List Files230231### Query parameters232233- `ids: optional array of string`234235 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.236237- `limit: optional number`238239 Number of items to return per page.240241 Defaults to `20`. Ranges from `1` to `1000`.242243 default: 20, maximum: 1000, minimum: 1244245- `page: optional string`246247 Opaque page cursor returned in a prior list response's `next_page`. Prefixed `page_`.248249- `scope_id: optional string`250251 Filter by scope ID. Only returns files associated with the specified scope (e.g., a session ID).252253### Headers254255- `"anthropic-beta": optional array of AnthropicBeta`256257 Optional header to specify the beta version(s) you want to use.258259 - `string`260261 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more`262263 - `"message-batches-2024-09-24"`264265 - `"prompt-caching-2024-07-31"`266267 - `"computer-use-2024-10-22"`268269 - `"computer-use-2025-01-24"`270271 - `"pdfs-2024-09-25"`272273 - `"token-counting-2024-11-01"`274275 - `"token-efficient-tools-2025-02-19"`276277 - `"output-128k-2025-02-19"`278279 - `"files-api-2025-04-14"`280281 - `"mcp-client-2025-04-04"`282283 - `"mcp-client-2025-11-20"`284285 - `"dev-full-thinking-2025-05-14"`286287 - `"interleaved-thinking-2025-05-14"`288289 - `"code-execution-2025-05-22"`290291 - `"extended-cache-ttl-2025-04-11"`292293 - `"context-1m-2025-08-07"`294295 - `"context-management-2025-06-27"`296297 - `"model-context-window-exceeded-2025-08-26"`298299 - `"skills-2025-10-02"`300301 - `"fast-mode-2026-02-01"`302303 - `"output-300k-2026-03-24"`304305 - `"user-profiles-2026-03-24"`306307 - `"user-profiles-2026-08-18"`308309 - `"user-profiles-2026-09-04"`310311 - `"advisor-tool-2026-03-01"`312313 - `"managed-agents-2026-04-01"`314315 - `"cache-diagnosis-2026-04-07"`316317 - `"dreaming-2026-04-21"`318319 - `"thinking-token-count-2026-05-13"`320321 - `"server-side-fallback-2026-06-01"`322323 - `"server-side-fallback-2026-07-01"`324325 - `"fallback-credit-2026-06-01"`326327 - `"fallback-credit-2026-07-01"`328329 - `"agent-memory-2026-07-22"`330331 - `"mid-conversation-tool-changes-2026-07-01"`332333 - `"compact-2026-01-12"`334335 - `"computer-use-2025-11-24"`336337 - `"mcp-tunnels-2026-06-22"`338339 - `"structured-outputs-2025-11-13"`340341 - `"task-budgets-2026-03-13"`342343 - `"thinking-display-updates-2026-08-18"`344345 - `"ce-user-management-2026-07-13"`346347 - `"mid-conversation-output-config-2026-07-01"`348349 - `"thinking-binding-controls-2026-08-01"`350351 - `"mid-conversation-system-clear-at-2026-08-21"`352353 - `"compact-2026-09-04"`354355- `"anthropic-workspace-id": optional string`356357### Returns358359- `data: array of BetaFileMetadata`360361 List of file metadata objects.362363 - `type: "file"`364365 Object type.366367 For files, this is always `"file"`.368369 - `id: string`370371 Unique object identifier.372373 The format and length of IDs may change over time.374375 - `created_at: string`376377 RFC 3339 datetime string representing when the file was created.378379 format: date-time380381 - `filename: string`382383 Original filename of the uploaded file.384385 maxLength: 500, minLength: 1386387 - `mime_type: string`388389 MIME type of the file.390391 maxLength: 255, minLength: 1392393 - `size_bytes: number`394395 Size of the file in bytes.396397 minimum: 0398399 - `downloadable: optional boolean`400401 Whether the file can be downloaded.402403 default: false404405 - `expires_at: optional string or null`406407 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.408409 format: date-time410411 - `scope: optional BetaFileScope or null`412413 The scope of this file, indicating the context in which it was created (e.g., a session).414415 - `type: "session"`416417 The type of scope (e.g., `"session"`).418419 - `id: string`420421 The ID of the scoping resource (e.g., the session ID).422423- `next_page: optional string or null`424425 Opaque cursor for the next page. Supply as `?page=` to fetch the next page; null when there are no more results.426427### Example428429```bash430curl https://api.anthropic.com/v1/files \431 -H 'anthropic-version: 2023-06-01' \432 -H "X-Api-Key: $ANTHROPIC_API_KEY"433```434435#### Response (200)436437```json438{439 "data": [440 {441 "id": "file_011CNha8iCJcU1wXNR6q4V8w",442 "created_at": "2025-04-15T18:37:24.100435Z",443 "filename": "document.pdf",444 "mime_type": "application/pdf",445 "size_bytes": 102400,446 "type": "file",447 "downloadable": false,448 "expires_at": "2025-05-15T18:37:24.100435Z",449 "scope": {450 "id": "id",451 "type": "session"452 }453 }454 ],455 "next_page": "next_page"456}457```458459## Download File460461**GET** `/v1/files/{file_id}/content`462463Download File464465### Path parameters466467- `file_id: string`468469 ID of the File.470471### Headers472473- `"anthropic-beta": optional array of AnthropicBeta`474475 Optional header to specify the beta version(s) you want to use.476477 - `string`478479 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more`480481 - `"message-batches-2024-09-24"`482483 - `"prompt-caching-2024-07-31"`484485 - `"computer-use-2024-10-22"`486487 - `"computer-use-2025-01-24"`488489 - `"pdfs-2024-09-25"`490491 - `"token-counting-2024-11-01"`492493 - `"token-efficient-tools-2025-02-19"`494495 - `"output-128k-2025-02-19"`496497 - `"files-api-2025-04-14"`498499 - `"mcp-client-2025-04-04"`500501 - `"mcp-client-2025-11-20"`502503 - `"dev-full-thinking-2025-05-14"`504505 - `"interleaved-thinking-2025-05-14"`506507 - `"code-execution-2025-05-22"`508509 - `"extended-cache-ttl-2025-04-11"`510511 - `"context-1m-2025-08-07"`512513 - `"context-management-2025-06-27"`514515 - `"model-context-window-exceeded-2025-08-26"`516517 - `"skills-2025-10-02"`518519 - `"fast-mode-2026-02-01"`520521 - `"output-300k-2026-03-24"`522523 - `"user-profiles-2026-03-24"`524525 - `"user-profiles-2026-08-18"`526527 - `"user-profiles-2026-09-04"`528529 - `"advisor-tool-2026-03-01"`530531 - `"managed-agents-2026-04-01"`532533 - `"cache-diagnosis-2026-04-07"`534535 - `"dreaming-2026-04-21"`536537 - `"thinking-token-count-2026-05-13"`538539 - `"server-side-fallback-2026-06-01"`540541 - `"server-side-fallback-2026-07-01"`542543 - `"fallback-credit-2026-06-01"`544545 - `"fallback-credit-2026-07-01"`546547 - `"agent-memory-2026-07-22"`548549 - `"mid-conversation-tool-changes-2026-07-01"`550551 - `"compact-2026-01-12"`552553 - `"computer-use-2025-11-24"`554555 - `"mcp-tunnels-2026-06-22"`556557 - `"structured-outputs-2025-11-13"`558559 - `"task-budgets-2026-03-13"`560561 - `"thinking-display-updates-2026-08-18"`562563 - `"ce-user-management-2026-07-13"`564565 - `"mid-conversation-output-config-2026-07-01"`566567 - `"thinking-binding-controls-2026-08-01"`568569 - `"mid-conversation-system-clear-at-2026-08-21"`570571 - `"compact-2026-09-04"`572573- `"anthropic-workspace-id": optional string`574575### Example576577```bash578curl https://api.anthropic.com/v1/files/$FILE_ID/content \579 -H 'anthropic-version: 2023-06-01' \580 -H "X-Api-Key: $ANTHROPIC_API_KEY"581```582583## Get File Metadata584585**GET** `/v1/files/{file_id}`586587Get File Metadata588589### Path parameters590591- `file_id: string`592593 ID of the File.594595### Headers596597- `"anthropic-beta": optional array of AnthropicBeta`598599 Optional header to specify the beta version(s) you want to use.600601 - `string`602603 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more`604605 - `"message-batches-2024-09-24"`606607 - `"prompt-caching-2024-07-31"`608609 - `"computer-use-2024-10-22"`610611 - `"computer-use-2025-01-24"`612613 - `"pdfs-2024-09-25"`614615 - `"token-counting-2024-11-01"`616617 - `"token-efficient-tools-2025-02-19"`618619 - `"output-128k-2025-02-19"`620621 - `"files-api-2025-04-14"`622623 - `"mcp-client-2025-04-04"`624625 - `"mcp-client-2025-11-20"`626627 - `"dev-full-thinking-2025-05-14"`628629 - `"interleaved-thinking-2025-05-14"`630631 - `"code-execution-2025-05-22"`632633 - `"extended-cache-ttl-2025-04-11"`634635 - `"context-1m-2025-08-07"`636637 - `"context-management-2025-06-27"`638639 - `"model-context-window-exceeded-2025-08-26"`640641 - `"skills-2025-10-02"`642643 - `"fast-mode-2026-02-01"`644645 - `"output-300k-2026-03-24"`646647 - `"user-profiles-2026-03-24"`648649 - `"user-profiles-2026-08-18"`650651 - `"user-profiles-2026-09-04"`652653 - `"advisor-tool-2026-03-01"`654655 - `"managed-agents-2026-04-01"`656657 - `"cache-diagnosis-2026-04-07"`658659 - `"dreaming-2026-04-21"`660661 - `"thinking-token-count-2026-05-13"`662663 - `"server-side-fallback-2026-06-01"`664665 - `"server-side-fallback-2026-07-01"`666667 - `"fallback-credit-2026-06-01"`668669 - `"fallback-credit-2026-07-01"`670671 - `"agent-memory-2026-07-22"`672673 - `"mid-conversation-tool-changes-2026-07-01"`674675 - `"compact-2026-01-12"`676677 - `"computer-use-2025-11-24"`678679 - `"mcp-tunnels-2026-06-22"`680681 - `"structured-outputs-2025-11-13"`682683 - `"task-budgets-2026-03-13"`684685 - `"thinking-display-updates-2026-08-18"`686687 - `"ce-user-management-2026-07-13"`688689 - `"mid-conversation-output-config-2026-07-01"`690691 - `"thinking-binding-controls-2026-08-01"`692693 - `"mid-conversation-system-clear-at-2026-08-21"`694695 - `"compact-2026-09-04"`696697- `"anthropic-workspace-id": optional string`698699### Returns700701- `BetaFileMetadata object`702703 - `type: "file"`704705 Object type.706707 For files, this is always `"file"`.708709 - `id: string`710711 Unique object identifier.712713 The format and length of IDs may change over time.714715 - `created_at: string`716717 RFC 3339 datetime string representing when the file was created.718719 format: date-time720721 - `filename: string`722723 Original filename of the uploaded file.724725 maxLength: 500, minLength: 1726727 - `mime_type: string`728729 MIME type of the file.730731 maxLength: 255, minLength: 1732733 - `size_bytes: number`734735 Size of the file in bytes.736737 minimum: 0738739 - `downloadable: optional boolean`740741 Whether the file can be downloaded.742743 default: false744745 - `expires_at: optional string or null`746747 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.748749 format: date-time750751 - `scope: optional BetaFileScope or null`752753 The scope of this file, indicating the context in which it was created (e.g., a session).754755 - `type: "session"`756757 The type of scope (e.g., `"session"`).758759 - `id: string`760761 The ID of the scoping resource (e.g., the session ID).762763### Example764765```bash766curl https://api.anthropic.com/v1/files/$FILE_ID \767 -H 'anthropic-version: 2023-06-01' \768 -H "X-Api-Key: $ANTHROPIC_API_KEY"769```770771#### Response (200)772773```json774{775 "id": "file_011CNha8iCJcU1wXNR6q4V8w",776 "created_at": "2025-04-15T18:37:24.100435Z",777 "filename": "document.pdf",778 "mime_type": "application/pdf",779 "size_bytes": 102400,780 "type": "file",781 "downloadable": false,782 "expires_at": "2025-05-15T18:37:24.100435Z",783 "scope": {784 "id": "id",785 "type": "session"786 }787}788```789790## Delete File791792**DELETE** `/v1/files/{file_id}`793794Delete File795796### Path parameters797798- `file_id: string`799800 ID of the File.801802### Headers803804- `"anthropic-beta": optional array of AnthropicBeta`805806 Optional header to specify the beta version(s) you want to use.807808 - `string`809810 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more`811812 - `"message-batches-2024-09-24"`813814 - `"prompt-caching-2024-07-31"`815816 - `"computer-use-2024-10-22"`817818 - `"computer-use-2025-01-24"`819820 - `"pdfs-2024-09-25"`821822 - `"token-counting-2024-11-01"`823824 - `"token-efficient-tools-2025-02-19"`825826 - `"output-128k-2025-02-19"`827828 - `"files-api-2025-04-14"`829830 - `"mcp-client-2025-04-04"`831832 - `"mcp-client-2025-11-20"`833834 - `"dev-full-thinking-2025-05-14"`835836 - `"interleaved-thinking-2025-05-14"`837838 - `"code-execution-2025-05-22"`839840 - `"extended-cache-ttl-2025-04-11"`841842 - `"context-1m-2025-08-07"`843844 - `"context-management-2025-06-27"`845846 - `"model-context-window-exceeded-2025-08-26"`847848 - `"skills-2025-10-02"`849850 - `"fast-mode-2026-02-01"`851852 - `"output-300k-2026-03-24"`853854 - `"user-profiles-2026-03-24"`855856 - `"user-profiles-2026-08-18"`857858 - `"user-profiles-2026-09-04"`859860 - `"advisor-tool-2026-03-01"`861862 - `"managed-agents-2026-04-01"`863864 - `"cache-diagnosis-2026-04-07"`865866 - `"dreaming-2026-04-21"`867868 - `"thinking-token-count-2026-05-13"`869870 - `"server-side-fallback-2026-06-01"`871872 - `"server-side-fallback-2026-07-01"`873874 - `"fallback-credit-2026-06-01"`875876 - `"fallback-credit-2026-07-01"`877878 - `"agent-memory-2026-07-22"`879880 - `"mid-conversation-tool-changes-2026-07-01"`881882 - `"compact-2026-01-12"`883884 - `"computer-use-2025-11-24"`885886 - `"mcp-tunnels-2026-06-22"`887888 - `"structured-outputs-2025-11-13"`889890 - `"task-budgets-2026-03-13"`891892 - `"thinking-display-updates-2026-08-18"`893894 - `"ce-user-management-2026-07-13"`895896 - `"mid-conversation-output-config-2026-07-01"`897898 - `"thinking-binding-controls-2026-08-01"`899900 - `"mid-conversation-system-clear-at-2026-08-21"`901902 - `"compact-2026-09-04"`903904- `"anthropic-workspace-id": optional string`905906### Returns907908- `BetaDeletedFile object`909910 - `type: optional "file_deleted"`911912 Deleted object type.913914 For file deletion, this is always `"file_deleted"`.915916 default: file_deleted917918 - `id: string`919920 ID of the deleted file.921922### Example923924```bash925curl https://api.anthropic.com/v1/files/$FILE_ID \926 -X DELETE \927 -H 'anthropic-version: 2023-06-01' \928 -H "X-Api-Key: $ANTHROPIC_API_KEY"929```930931#### Response (200)932933```json934{935 "id": "file_011CNha8iCJcU1wXNR6q4V8w",936 "type": "file_deleted"937}938```939940## Domain types941942### Beta Deleted File943944- `BetaDeletedFile object`945946 - `type: optional "file_deleted"`947948 Deleted object type.949950 For file deletion, this is always `"file_deleted"`.951952 default: file_deleted953954 - `id: string`955956 ID of the deleted file.957958### Beta File Metadata959960- `BetaFileMetadata object`961962 - `type: "file"`963964 Object type.965966 For files, this is always `"file"`.967968 - `id: string`969970 Unique object identifier.971972 The format and length of IDs may change over time.973974 - `created_at: string`975976 RFC 3339 datetime string representing when the file was created.977978 format: date-time979980 - `filename: string`981982 Original filename of the uploaded file.983984 maxLength: 500, minLength: 1985986 - `mime_type: string`987988 MIME type of the file.989990 maxLength: 255, minLength: 1991992 - `size_bytes: number`993994 Size of the file in bytes.995996 minimum: 0997998 - `downloadable: optional boolean`9991000 Whether the file can be downloaded.10011002 default: false10031004 - `expires_at: optional string or null`10051006 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.10071008 format: date-time10091010 - `scope: optional BetaFileScope or null`10111012 The scope of this file, indicating the context in which it was created (e.g., a session).10131014 - `type: "session"`10151016 The type of scope (e.g., `"session"`).10171018 - `id: string`10191020 The ID of the scoping resource (e.g., the session ID).10211022### Beta File Scope10231024- `BetaFileScope object`10251026 - `type: "session"`10271028 The type of scope (e.g., `"session"`).10291030 - `id: string`10311032 The ID of the scoping resource (e.g., the session ID).1033