Firmware Archive API

A secure, scalable REST API for firmware management and distribution. Built on Cloudflare's edge infrastructure for global performance.

REST API

v1.0

Global CDN

Base URL

https://firmware-api-cf.product-eef.workers.dev

Authentication

The Firmware Archive API currently operates in open mode for public access. No authentication is required for standard operations.

Security Note

Rate limiting is enforced to prevent abuse. Future versions may include API key authentication for enhanced features.

Rate Limiting

Upload Limits

10 uploads per hour per IP address
25MB maximum file size
Automatic reset after 60 minutes

Response Headers

X-RateLimit-Limit: 10

X-RateLimit-Remaining: 7

X-RateLimit-Reset: 1691234567

Error Handling

The API uses conventional HTTP response codes to indicate the success or failure of requests.

200

Request successful

400

Bad Request

Missing required parameters or invalid file format

409

Conflict

Duplicate firmware detected (identical SHA256 hash) or analysis already in progress

413

Payload Too Large

File exceeds 25MB size limit

429

Too Many Requests

Rate limit exceeded

Error Response Format

{
  "success": false,
  "error": "Bad Request",
  "message": "Missing required field: name"
}

API Reference

GET

List Firmware

/firmwares

Retrieves a paginated list of all firmware files with metadata including file sizes, SHA256 hashes, upload information, and analysis status.

Response Example

[
  {
    "id": "af9636f2-98d7-477b-b53a-22a1daed4038",
    "name": "TPLink WR841N Firmware",
    "vendor": "TPLink",
    "device": "Router",
    "version": "v4.16.9",
    "original_filename": "wr841nv9_en_3_16_9_up_boot.bin",
    "upload_date": "2025-08-04T22:56:06.000Z",
    "sha256": "886f82f276eef90f87fb69c16717b6fdc3666a5f...",
    "file_size": 4194304,
    "analysis_status": "completed",
    "analysis_queued_at": "2025-08-05T09:08:10.662Z",
    "analysis_completed_at": "2025-08-05T09:15:42.123Z"
  },
  {
    "id": "a43a8cf8-f003-4335-bd5f-f006d17e7203",
    "name": "DIR-822 Firmware",
    "vendor": "D-Link",
    "device": "Router", 
    "version": "v2.5.5",
    "original_filename": "DIR_822C1A_2.5.5.bin",
    "upload_date": "2025-08-04T22:53:22.000Z",
    "sha256": "606c5fd73e87ff172aad2c5546b5095d093a1452...",
    "file_size": 5082470,
    "analysis_status": "pending",
    "analysis_queued_at": null,
    "analysis_completed_at": null
  }
]

POST

Upload Firmware

/upload

Uploads a new firmware file with metadata. Files are automatically scanned for duplicates using SHA256 hashing.

Request Body

Content-Type: multipart/form-data

file*Binary file data (max 25MB)

name*Firmware display name

vendor*Manufacturer name

device*Device type (Router, Switch, etc.)

version*Firmware version

Success Response

{
  "success": true,
  "firmware_id": "af9636f2-98d7-477b-b53a-22a1daed4038",
  "message": "Firmware uploaded successfully."
}

Duplicate Error Response

{
  "success": false,
  "error": "Duplicate firmware detected",
  "message": "A firmware file with identical content already exists",
  "existing_firmware": {
    "id": "existing-id",
    "name": "Existing Firmware Name",
    "vendor": "Vendor",
    "device": "Device",
    "version": "v1.0"
  }
}

GET

Download Firmware

/firmwares/{id}/download

Downloads a specific firmware file by its unique identifier. Returns the original binary file with appropriate headers.

Path Parameters

id*UUID of the firmware file

# Download to file
curl -O "https://firmware-api-cf.product-eef.workers.dev/firmwares/af9636f2-98d7-477b-b53a-22a1daed4038/download"

# Download with custom filename
curl -o "my-firmware.bin" \
  "https://firmware-api-cf.product-eef.workers.dev/firmwares/af9636f2-98d7-477b-b53a-22a1daed4038/download"

POST

Analyze Firmware

/analyze/{id}

Queues a firmware file for security analysis. The firmware metadata is sent to a Cloudflare Queue for processing. Prevents duplicate analysis requests.

Path Parameters

id*UUID of the firmware file to analyze

Analysis Status Values

pending

Not yet queued for analysis

queued

Queued for analysis

processing

Currently being analyzed

completed

Analysis completed successfully

failed

Analysis failed with errors

Success Response

{
  "success": true,
  "message": "Firmware analysis request queued successfully",
  "firmware_id": "af9636f2-98d7-477b-b53a-22a1daed4038",
  "queued_at": "2025-08-05T09:08:10.662Z",
  "status": "queued"
}

Already Queued Response (409)

{
  "success": false,
  "error": "Analysis already in progress",
  "message": "Firmware analysis is already queued",
  "current_status": "queued",
  "queued_at": "2025-08-05T09:08:10.662Z"
}

PUT

Update Analysis Status

/analyze/{id}/status

Updates the analysis status of a firmware file. This endpoint is typically used by analysis processors to report progress and results.

Path Parameters

id*UUID of the firmware file

Request Body

Content-Type: application/json

status*New status: "processing", "completed", or "failed"

resultsAnalysis results object (optional)

error_messageError description for failed status (optional)

Success Response

{
  "success": true,
  "message": "Analysis status updated to completed",
  "firmware_id": "af9636f2-98d7-477b-b53a-22a1daed4038",
  "status": "completed",
  "updated_at": "2025-08-05T09:15:42.123Z"
}

Example Request Body

{
  "status": "completed",
  "results": {
    "vulnerabilities_found": 2,
    "security_score": 78,
    "analysis_duration": "45.2s",
    "findings": [
      {
        "type": "weak_encryption",
        "severity": "medium",
        "description": "Uses outdated SSL/TLS configuration"
      }
    ]
  }
}

SDKs & Libraries

The API follows REST conventions and can be integrated with any HTTP client. Here are some recommended libraries:

JavaScript/TypeScript

Fetch API (native)
Axios
SWR (React)
TanStack Query

Other Languages

Python: requests, httpx
Go: net/http, resty
Rust: reqwest
Java: OkHttp, HttpClient

Postman Collection

Import our Postman collection to quickly test the API endpoints with pre-configured requests.