---
title: Upload a file (POST /api/v2/files) | HelpRange API
description: POST /api/v2/files: Uploads a file into a folder (folder_id, or your default folder).
url: https://www.helprange.com/developers/api/upload-file
---

POST

# Upload a file

`https://www.helprange.com/api/v2/files`

Uploads a file into a folder (folder_id, or your default folder). Send the file as multipart "file" (recommended), as a public "file_url" HelpRange downloads (within 30 seconds), or as "content_base64" with "filename" in a JSON body. Limit: the team's upload limit, 100 MB per file (larger files only in the panel). Over it: 413 with code FILE_TOO_LARGE or REQUEST_TOO_LARGE; the team's daily upload limit: 429 with code UPLOAD_LIMIT.

**Plans:** Pro, Max, Unlimited, Deal Room Pass, trial. **Auth:** `Authorization: Bearer hr_live_…` (team key), `X-API-Key`, `Authorization: Api-Key <key>` or an OAuth `Bearer` token. **Scope:** `documents:write`. **Operation id:** `uploadFile`

**Header** `Idempotency-Key` (optional, up to 255 characters): retry with the same key and body within 24 hours and you get the first response back (`Idempotent-Replayed: true`) – the request is not run twice. Another body: `422 idempotency_key_reused`; still running: `409 idempotency_key_in_progress`. [More](https://www.helprange.com/developers/api#idempotency).

## Request body

One of: multipart "file", "file_url" or "content_base64". Content types: `multipart/form-data`, `application/json`, `application/x-www-form-urlencoded`.

| Field | Type | Description |
|---|---|---|
| `file` | binary (multipart) | The file, as multipart/form-data (recommended). |
| `folder_id` | integer | Target folder (default: your default folder). |
| `file_url` | string (uri) | A public URL of the file. |
| `content_base64` | string | The file, base64-encoded. |
| `filename` | string | File name (default: the uploaded / downloaded name, or document.pdf). |

## Example request

```
curl -X POST https://www.helprange.com/api/v2/files \
  -H "X-API-Key: $HELPRANGE_API_KEY" \
  -F 'file=@proposal.pdf' \
  -F folder_id=31
```

```
import { openAsBlob } from 'node:fs';  // Node 20+; in a browser use a file input

const form = new FormData();
form.append('file', await openAsBlob('proposal.pdf'), 'proposal.pdf');
form.append('folder_id', '31');

const res = await fetch('https://www.helprange.com/api/v2/files', {
  method: 'POST',
  headers: {'X-API-Key': process.env.HELPRANGE_API_KEY},
  body: form,
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status}: ${data.error || data.message || data.reason}`);
console.log(data);
```

```
import os

import requests

with open('proposal.pdf', 'rb') as f:
    r = requests.post(
        'https://www.helprange.com/api/v2/files',
        headers={'X-API-Key': os.environ['HELPRANGE_API_KEY']},
        files={'file': f},
        data={
            "folder_id": 31,
        },
        timeout=60,
    )
r.raise_for_status()
print(r.json())
```

The samples read the key from the `HELPRANGE_API_KEY` environment variable.

## Responses

| Status | Description |
|---|---|
| `201` | Created |
| `400` | Invalid input – the message says which parameter. |
| `401` | Missing or invalid API key / OAuth token. Team keys: code invalid_key, key_revoked, key_expired or key_owner_removed. |
| `402` | Your plan does not include the REST API (the Free plan) or this feature (e.g. NDA needs Max). |
| `403` | The team API key lacks the scope this endpoint needs. |
| `404` | Not found – or not yours (the API never says which). |
| `405` | Wrong HTTP method for this endpoint. |
| `409` | The data room is frozen, the signed PDF is not ready yet, (webhooks) the team already has an endpoint / the endpoint is turned off, or (code idempotency_key_in_progress) a request with the same Idempotency-Key is still running – retry in a few seconds. |
| `413` | The file or the request body is over the upload limit (code FILE_TOO_LARGE / REQUEST_TOO_LARGE). |
| `422` | code idempotency_key_reused: this Idempotency-Key was already used in the last 24 hours with a different request (method, path or body). Use a new key for a new request. |
| `423` | The target data room is frozen (code ROOM_FROZEN). |
| `429` | A usage limit was reached – wait Retry-After seconds. |

Example response · 201

```
{
  "id": 250,
  "name": "proposal.pdf",
  "folder_id": 31,
  "type": "document",
  "pages": 12,
  "default_link": "https://www.helprange.com/view/471dcc98874d4d0cb7c3eb1874c4e3db/proposal.pdf"
}
```

## Try it

**Uses your real account.** The request goes from your browser straight to `www.helprange.com` with your API key and acts as you – this POST **changes data**. The key stays in this page (in this tab's session storage only if you tick the box), is never put in a URL and is not sent to analytics. Do not paste a key on a shared computer.
 API key

  Remember in this tab   File (multipart – leave empty to send the JSON body below)

folder_id (form field)

filename (form field)  JSON body { "file_url": "https://example.com/proposal.pdf", "folder_id": 31 }

```

```