File Upload API
File Upload API
Upload investigation files securely to the Cursed Tools platform. Files are automatically encrypted when uploaded by authenticated users with encryption keys.
Prerequisites
Before uploading files, ensure you have:
- Authentication configured with your API token
- Valid file types for investigation (EVTX, log files, etc.)
- Appropriate file sizes within upload limits
Endpoint
POST /upload
Security & Encryption
- TLS transmission: Files uploaded over secure HTTPS connections
- Conditional encryption: Files encrypted when uploaded by authenticated users with encryption keys
- In-memory only operations: Files never exist unencrypted on disk
- Per-file encryption keys: Each encrypted file receives a unique encryption key
- Unauthenticated uploads: Stored unencrypted for unauthenticated users
Request Parameters
Headers
| Parameter | Type | Required | Description |
|---|---|---|---|
X-Cursed-Api-Token | Header | No | Your API authentication token (UUID v4 format) |
X-Cursed-Api-Enc-Key | Header | Conditional* | Your encryption key for encrypted uploads and encrypted workload access |
Content-Type | Header | Yes | Must be multipart/form-data |
*Required when accessing workloads that work with files or data that has been encrypted
Form Data
| Parameter | Type | Required | Description |
|---|---|---|---|
files | File(s) | Yes | Investigation files to upload |
File Validation Rules:
- File size limits: Up to 250MB per file
- Upload timeout: 30 seconds maximum
- Multiple files: Upload multiple files in a single request
- Encoding: Binary and text formats supported
Response Format
Success Response
{
"file_ids": [
["550e8400-e29b-41d4-a716-446655440000", "security.evtx"],
["550e8400-e29b-41d4-a716-446655440001", "system.evtx"]
],
"message": "Files uploaded successfully"
}
Response Fields
| Field | Type | Description |
|---|---|---|
file_ids | Array | Array of file_id, filename pairs for uploaded files |
message | String | Success confirmation message |
File ID Format:
- UUID v4: Unique identifier for each uploaded file
- Persistent: File ID remains constant for the lifetime of the file
- Required for analysis: Use file IDs in subsequent API calls
Error Responses
All error responses return a plain text message with an appropriate HTTP status code.
Common Errors
Invalid Multipart Form
Status Code: 400 Bad Request
Response: Failed to process multipart form: [details]
Missing Encryption Key (for authenticated users)
Status Code: 400 Bad Request
Response: Encryption key is required
Invalid API Token Format
Status Code: 400 Bad Request
Response: X-Cursed-Api-Token must be a valid UUID v4
Invalid Encryption Key Format
Status Code: 400 Bad Request
Response: X-Cursed-Api-Enc-Key is invalid
File Too Large
Status Code: 413 Payload Too Large
Upload Timeout
Status Code: 408 Request Timeout
Server Storage Error
Status Code: 500 Internal Server Error
Response: An error occurred while processing your request. If you would like to report it contact us via the feedback form on cursed.tools/feedback and quote the following ID: [error-uuid]
Examples
cURL
# Unauthenticated upload (unencrypted storage)
curl -X POST "https://api.cursed.tools/analysis/upload" \
-F "files=@/path/to/security.evtx"
# Authenticated upload with encryption
curl -X POST "https://api.cursed.tools/analysis/upload" \
-H "X-Cursed-Api-Token: 550e8400-e29b-41d4-a716-446655440000" \
-H "X-Cursed-Api-Enc-Key: dGhpcyBpcyBhIGJhc2U2NCBlbmNvZGVkIGV4YW1wbGU=" \
-F "files=@/path/to/security.evtx"
# Multiple files upload
curl -X POST "https://api.cursed.tools/analysis/upload" \
-H "X-Cursed-Api-Token: 550e8400-e29b-41d4-a716-446655440000" \
-H "X-Cursed-Api-Enc-Key: dGhpcyBpcyBhIGJhc2U2NCBlbmNvZGVkIGV4YW1wbGU=" \
-F "files=@/path/to/security.evtx" \
-F "files=@/path/to/system.evtx"
Upload Best Practices
Security Considerations
- Use authentication: Always provide API token for account storage and processing
- Include encryption key: Essential for private encrypted uploads
- Verify file integrity: Check file_ids in response match uploads
- Monitor upload limits: Respect file size and timeout constraints
Performance Optimization
- Batch uploads: Use multiple files in single request when possible
- Check file sizes: Verify files are under 250MB limit before upload
- Handle timeouts: Implement retry logic for large files
- Monitor quota: Track API usage to avoid limits
Error Handling
- Validate responses: Check HTTP status codes and response format
- Parse error messages: Use plain text error responses for debugging
- Implement retries: Handle temporary network or server issues
- Log upload attempts: Track successful and failed uploads
File Management After Upload
Once files are uploaded successfully:
- Store file IDs: Save the returned file_ids for future reference
- Start analysis: Use file IDs with analysis endpoints
- Monitor jobs: Track analysis progress via job status endpoints
- Retrieve results: Download analysis results when complete
Next Steps
- Parse EVTX Files - Analyze Windows Event Logs
- Run Sigma Rules - Execute detection rules
- Check Job Status - Monitor analysis progress
File uploads are the starting point for analysis workflows. Ensure proper authentication and encryption for sensitive investigation data.
List Files
Retrieves a list of all files owned by the authenticated user. Returns file metadata including ID, name, creation date, visibility, and encryption status.
Delete Job
Permanently deletes one or more analysis jobs and their associated results. Only the job owner can delete jobs. Once deleted, jobs and their results cannot be recovered.