Upload Image

Upload a binary image to the Binarly Transparency Platform for security analysis. The binary never passes through the API server: you upload it to a pre-signed storage URL, then create the image from that uploaded file.

Generate upload URL

Request a temporary file ID and a time-limited pre-signed URL.

Upload the binary

Upload your file directly to the pre-signed URL.

Create the image

Create an image from the uploaded file. By default, this also starts the first scan.

Step 1: Generate upload URL

Call this endpoint to create a temporary file and receive its upload URL.

Request

RES=$(curl -sS --fail-with-body -X POST \
  -H "Authorization: Bearer ${TOKEN}" \
  "${BINARLY_API_URL}/api/v4/products/${BINARLY_PRODUCT_ID}/tempFiles:generateUploadUrl")

# Keep the values for Steps 2 and 3
TEMP_FILE_ID=$(jq -r '.id' <<< "$RES")
UPLOAD_URL=$(jq -r '.uploadUrl' <<< "$RES")

Response

The endpoint returns 201 Created with the temporary file id and the uploadUrl for the next step.

{
  "id": "01K6Z3V9Q2M7XH4D8RTN5B1C0E",
  "uploadUrl": "https://storage.googleapis.com/..."
}

The temporary file belongs to the product in the request path and to the user or API client that generated it. Only that same identity can create an image from it, and each temporary file can be used once.

Step 2: Upload the binary

Upload your binary to the uploadUrl from Step 1 with a PUT request.

Request

curl -X PUT --data-binary @"path/to/firmware.bin" "${UPLOAD_URL}"

This request does not need the Authorization header, because the URL itself is signed.

Step 3: Create the image

After the upload returns HTTP 200, create the image. Send the fields as a JSON body. Endpoint

POST <BINARLY_API_URL>/api/v4/products/{productId}/images

Request body

string

required

The id returned in Step 1.

string

required

A human-readable name for the image. Names must be unique within a product.

string

required

The file name to record for the uploaded binary, for example firmware.bin.

string

The image version. When set, it must be a full semantic version such as 1.0.0.

boolean

default:"true"

Start a scan of the image right after it is created. Set to false to create the image without scanning it.

Request

curl -X POST \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "tempFileId": "'"${TEMP_FILE_ID}"'",
    "name": "My Firmware Image",
    "version": "1.0.0",
    "filename": "firmware.bin"
  }' \
  "${BINARLY_API_URL}/api/v4/products/${BINARLY_PRODUCT_ID}/images"

Response

The endpoint returns 201 Created with the new image. When a scan was started, the scans array contains it.

{
  "id": "01K6Z3XA7F5PJ2N9C4VQ8D6M1R",
  "name": "My Firmware Image",
  "version": "1.0.0",
  "createTime": "2026-10-09T12:00:00Z",
  "isArchived": false,
  "author": {
    "id": "01JV49FS1ZSGQ72NN6E0RXK3T0",
    "userId": "01JV49FS1ZSGQ72NN6E0RXK3T0",
    "email": "user@example.com",
    "status": "active"
  },
  "parent": "products/01JQPGDX8QW0YJ0XEKV1EVG534",
  "scans": [
    {
      "id": "01K6Z3XA8B2TQ7W1H5KD9E3N4S",
      "latestScanState": {
        "type": "new"
      }
    }
  ]
}

Use the image id to poll the scan or upload debug symbols.

Errors

Status	Cause
`400`	A required field is missing, `version` is not a valid semantic version, or the uploaded file is empty. Also returned when `tempFileId` was never uploaded to, was already used, or was generated by a different user or API client.
`404`	The product does not exist.
`409`	An image with the same `name` already exists in the product.
`413`	The uploaded file exceeds the maximum image size for your deployment.
`429`	Your organization reached its monthly scan quota. See Quotas. Only returned when `createScan` is `true`.

If image creation fails, the temporary file cannot be reused. Repeat the workflow from Step 1 to retry.

Overview

Use Cases

Reference

Step 1: Generate upload URL

Response

Step 2: Upload the binary

Step 3: Create the image

Request body

Response

Errors