> ## Documentation Index
> Fetch the complete documentation index at: https://docs.binarly.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload Image

Upload a binary image to the Binarly Transparency Platform for security analysis. The upload process uses a secure, three-step workflow involving a pre-signed URL.

<Steps>
  <Step title="Generate Upload URL">
    Obtain a secure, time-limited pre-signed URL for uploading your firmware binary.
  </Step>

  <Step title="Upload a Binary">
    Upload your file directly to the provided pre-signed URL.
  </Step>

  <Step title="Finalize Upload">
    Notify the platform that the upload is complete to trigger the security analysis.
  </Step>
</Steps>

## Step 1: Generate Upload URL

Call this endpoint to receive a temporary upload URL and a unique file ID.

<CodeGroup>
  ```bash Request theme={null}
  # Replace ${BINARLY_PRODUCT_ID} with your product ID
  curl -H "Authorization: Bearer ${TOKEN}" \
    "${BINARLY_API_URL}/api/v4/products/${BINARLY_PRODUCT_ID}/tempFiles:generateUploadUrl"
  ```
</CodeGroup>

### Response

The response contains the `uploadUrl` for the next step and an `id` to identify the file.

```json theme={null}
{
  "id": "01ABC123DEF456...",
  "uploadUrl": "https://storage.googleapis.com/..."
}
```

## Step 2: Upload a Binary

Upload your binary file to the `uploadUrl` obtained in Step 1. Use a **PUT** request with the binary content.

<CodeGroup>
  ```bash Request theme={null}
  # Upload the file binary to the pre-signed URL
  curl -X PUT --data-binary @"path/to/firmware.bin" "${UPLOAD_URL}"
  ```
</CodeGroup>

> <Note>
>   This request does not require the `Authorization` header, as the URL itself is signed.
> </Note>

## Step 3: Finalize Upload

Once the binary upload is successful (HTTP 200), call this endpoint to finalize the process and start the scan.

### request

<ParamField body="tempFileId" type="string" required>
  The `id` received from Step 1.
</ParamField>

<ParamField body="imageName" type="string" required>
  A human-readable name for the binary image.
</ParamField>

<ParamField body="version" type="string">
  The binary file version string (e.g., "1.0.0").
</ParamField>

<ParamField body="file" type="file" required>
  The binary file. Required by the API even when using `tempFileId` (content is taken from pre-signed upload).
</ParamField>

<CodeGroup>
  ```bash Request theme={null}
  # Finalize the upload using tempFileId from Step 1
  curl -X POST \
    -H "Authorization: Bearer ${TOKEN}" \
    -F "tempFileId=${TEMP_FILE_ID}" \
    -F "imageName=My Firmware Image" \
    -F "version=1.0.0" \
    -F "file=@./firmware.bin" \
    "${BINARLY_API_URL}/api/v4/products/${BINARLY_PRODUCT_ID}/images:upload"
  ```
</CodeGroup>

### Response

Returns the created image object, confirming the scan has started.

```json theme={null}
{
  "id": "img_abc123",
  "name": "My Firmware Image",
  "version": "1.0.0",
  "createTime": "2026-01-28T12:00:00Z",
  "scans": [
    {
      "id": "scan_xyz789",
      "latestScanState": {
        "type": "new"
      }
    }
  ]
}
```