CEcensys
Threat Hunting
Adversary Investigation

Investigations: Create file upload

Changed on

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 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.

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

Query parameters

organization_idstring uuid required

The ID of a Censys organization to associate the request with. See the Getting Started docs for more information.

Example:11111111-2222-3333-4444-555555555555

Headers

X-Organization-IDstring uuid

The ID of a Censys organization to associate the request with. See the Getting Started docs for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter.

Example:11111111-2222-3333-4444-555555555555

Request body

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.

filenamestring

The original name of the file. Used only as display metadata on the investigation; it does not affect where the file is stored.

size_bytesinteger 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.

Example request

{
  "content_type": "application/pdf",
  "filename": "incident-report.pdf",
  "size_bytes": 1048576
}

Response

Upload prepared successfully

Example response

{
  "result": {
    "file_id": "file_550e8400-e29b-41d4-a716-446655440000"
  }
}

Changes