---
title: "Investigations: Create file upload"
method: POST
path: "/v3/threat-hunting/investigations/files"
tags: ["Threat Hunting", "Adversary Investigation"]
---

# Investigations: Create file upload

`POST /v3/threat-hunting/investigations/files`

## Request

- Base URL: `https://api.platform.censys.io`
- URL: `https://api.platform.censys.io/v3/threat-hunting/investigations/files`
- Auth: HTTP bearer

Prepare to attach an evidence file to an investigation. Use this endpoint to stage evidence, such as logs, malware reports, or alert exports, so an AI investigation can use it.<br><br>This endpoint does not accept the file. It returns a URL to send the file to and an identifier to pass to the [create job endpoint](https://docs.censys.com/reference/v3-threathunting-investigations-jobs-create) afterwards.<br><br>Upload the file with an HTTP PUT to `upload_url` and send `upload_headers` exactly as returned by this endpoint. The URL grants access to that one file and stops working at `expire_time`; a file uploaded before that stays usable afterwards. Prepare one upload per file.<br><br>Start the investigation promptly after uploading. There is a limit on how many uploaded files you may hold without using them and starting an investigation from a file releases its slot. A file that no investigation references is discarded once it passes the service's retention window for unused uploads. A file an investigation does reference is kept with that investigation for as long as the investigation itself.<br><br>To use this endpoint, your organization must have access to the Adversary Investigation module.<br><br>This endpoint does not cost any credits to execute.

## Query parameters

- `organization_id` string, uuid, required: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.

## Headers

- `X-Organization-ID` string, uuid: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter.

## Request body

- CreateInvestigationFileInputBody
  - `content_type` 'application/pdf' | 'text/html' | 'text/csv' | 'text/plain' | 'image/png' | 'image/jpeg' | 'image/webp', required: The media type of the file to upload. Send it bare: a type carrying parameters, such as a charset, is not accepted.
  - `filename` string: The original name of the file. Used only as display metadata on the investigation; it does not affect where the file is stored.
  - `size_bytes` integer, required: The size of the file in bytes. The largest a single file may be is set by the service and can change; sending more returns an unprocessable entity response. The upload itself is limited independently, so understating this does not raise the limit.

## Response `200`

Upload prepared successfully

- ResponseEnvelopeInvestigationFileUpload
  - `result` InvestigationFileUpload
    - `expire_time` string, date-time, required: When upload_url stops working. A file that was uploaded before then stays usable afterwards; only the URL expires.
    - `file_id` string, required: Identifier for the uploaded file, to be sent as a file_ids entry when starting an investigation. It is an opaque handle, not a storage location, and it is meant for one investigation.
    - `upload_headers` object, required: Send these headers on the PUT exactly as given. They are part of what the URL authorizes, so an upload that omits or changes one is rejected by storage.
    - `upload_url` string, required: Send the file bytes here with an HTTP PUT. The URL grants access to this one file and nothing else, and stops working at expire_time.

## Other responses

- `401`: Request does not contain a valid Authorization token
- `403`: User does not have permission to access this data
- `409`: Feature not enabled
- `413`: Request body too large
- `422`: Invalid input
- `429`: You are holding too many unused uploads
- `500`: Internal server error

## Changes

- **2026-11-03** `ec1686b0a36a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/censys/apis/censys-platform-api/changes/v3/threat-hunting/investigations/files/post.md)

---

[API](https://skmtc.dev/censys/apis/censys-platform-api.md) - [All operations](https://skmtc.dev/censys/apis/censys-platform-api/llms.txt) - [OpenAPI document](https://skmtc.dev/censys/apis/censys-platform-api/revisions/ec1686b0a36a?raw)