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

> ## Agent Instructions
> Treat these docs and the Whop MCP server as the source of truth for Whop API behavior. Don't infer endpoint behavior from marketing pages.
> MCP server: connect https://mcp.whop.com/mcp (streamable HTTP, browser sign-in, no API key in the client config) to search these docs and read or change live Whop data. Setup: https://docs.whop.com/developer/guides/ai_and_mcp.md
> Whop CLI: install with `curl -fsSL https://whop.com/install.sh | sh` to scaffold, run, and deploy Whop apps and websites. It acts on production, not the sandbox. Overview: https://docs.whop.com/cli/overview.md Agent mode: https://docs.whop.com/cli/agent-mode.md
> Hosting: Whop serves a site or app from the build `whop apps deploy` uploads, with rollbacks, secrets, and server logs. Guide: https://docs.whop.com/developer/websites/hosting.md
> Plugins: in Claude Code, run `/plugin marketplace add whopio/plugins`, then `/plugin install whop@whop`. Guide: https://docs.whop.com/developer/guides/plugins/claude-code.md Every agent tool: https://docs.whop.com/developer/ai/overview.md
> Environments: build and test in the sandbox (API `https://sandbox-api.whop.com/api/v1`, keys at https://sandbox.whop.com/dashboard/developer, SDK environment `Sandbox`; no real money). Production (API `https://api.whop.com/api/v1`, keys at https://whop.com/dashboard/developer, SDK environment `Production`, the SDK default) moves real money, so use it only at launch. The two share no accounts, keys, products, or webhooks, and their keys look identical: never mix them. Sandbox guide: https://docs.whop.com/developer/guides/sandbox.md Comparison: https://docs.whop.com/developer/quickstart.md
> API: send `Authorization: Bearer <API_KEY>` from your server only, and pin a dated version with the `Api-Version-Date` header. OpenAPI spec: https://api.whop.com/api/v1/openapi.json
> Which API: build on the Current API, whose pages live under https://docs.whop.com/api-reference/ (start at https://docs.whop.com/api-reference/overview.md). Pages under /api-reference/legacy/ are the Legacy API. Use one only when https://docs.whop.com/api-reference/stability.md lists the resource as Legacy-only.

# Bestanden rechtstreeks uploaden

> Upload bestanden naar Whop-opslag met presigned uploads in één deel of in meerdere delen

Uploads bij Whop gaan **rechtstreeks naar de opslag**. Wanneer je [Create File](https://docs.whop.com/nl/api-reference/files/create-file.md) aanroept, ontvangt Whop je bytes niet via de API. In plaats daarvan maakt Whop een bestandsrecord aan en geeft een **presigned upload-URL** terug, waar je de bytes zelf met `PUT` naartoe stuurt. Het bestand is bruikbaar zodra die bytes in de opslag van Whop zijn aangekomen.

Dit is de onderliggende flow in twee stappen achter de methoden `files.create` en `files.retrieve` van de SDK. Gebruik hem wanneer je vanuit de browser uploadt (zodat de bytes nooit je server raken) of werkt in een taal zonder SDK. Zo verstuur je ook bestanden die zo groot zijn dat ze in meerdere delen moeten.

> [!NOTE]
>
> De `/files`-endpoints vereisen API-versie `2026-08-21-1` of later. Elk request hieronder legt die vast met de header `Api-Version-Date`. Zie [API-versies](https://docs.whop.com/nl/developer/api/versioning.md).

## De levenscyclus van een upload

Elke upload bestaat uit drie stappen, of het nu om één deel gaat of om meerdere:

1. **Maak** het bestandsrecord aan → Whop retourneert een presigned bestemming en het bestand begint als `pending`.
2. **Upload** de bytes rechtstreeks naar de presigned URL's.
3. **Poll** [Retrieve File](https://docs.whop.com/nl/api-reference/files/retrieve-file.md) totdat `upload_status` `ready` is — dan zijn `url` en `size` ingevuld en kan de ID van het bestand overal worden gekoppeld waar Whop een document accepteert.

De `url` en `size` van een bestand blijven `null` totdat de verwerking klaar is. `upload_status` doorloopt `pending` → `processing` → `ready` (of `failed`).

## Upload in één deel

Gebruik één `PUT` voor alles onder een paar honderd megabyte.

**1. Maak het bestand aan**

Stuur de `filename` en optioneel een `visibility` (standaard `private`). De `upload_url` in de response is waar de bytes naartoe gaan, en `upload_headers` zijn de headers die je ermee moet meesturen.

```bash theme={null}
curl https://api.whop.com/api/v1/files \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Api-Version-Date: 2026-08-21-1" \
  -H "Content-Type: application/json" \
  -d '{ "filename": "terms.pdf", "visibility": "private" }'
```

```json theme={null}
{
  "object": "file",
  "id": "file_XXXXXXXX",
  "filename": "terms.pdf",
  "content_type": "application/pdf",
  "size": null,
  "url": null,
  "removed_by_moderation": false,
  "upload_status": "pending",
  "visibility": "private",
  "created_at": "2026-08-21T18:24:00.000Z",
  "width": null,
  "height": null,
  "blurhash": null,
  "duration_seconds": null,
  "waveform_url": null,
  "upload_url": "https://upload.whop.com/uploads/...&signature=...",
  "upload_headers": { "Content-Type": "application/pdf" },
  "multipart_upload_id": null,
  "multipart_upload_urls": null,
  "multipart_chunk_size": null
}
```

**2. Upload de bytes**

Stuur de inhoud van het bestand met `PUT` naar `upload_url`, met alle headers uit `upload_headers`. Dit request gaat rechtstreeks naar de bestandsopslag van Whop, **niet** naar `api.whop.com`, en bevat geen Whop-`Authorization`-header — de inloggegevens zitten in de presigned URL.

```bash theme={null}
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @terms.pdf
```

> [!WARNING]
>
> De presigned URL verloopt een uur nadat hij is uitgegeven. Maak het bestand aan vlak voordat je uploadt, en vraag een nieuwe aan als een `PUT` na lange tijd mislukt met `403`. URL's voor delen van een multipart-upload verlopen eerder, na 15 minuten.

**3. Poll totdat het bestand klaar is**

Haal het bestand op via de ID totdat `upload_status` `ready` wordt. Het veld `url` bevat dan een downloadlink: een permanente CDN-URL als het bestand `public` is, of een ondertekende, verlopende URL als het `private` is.

```bash theme={null}
curl https://api.whop.com/api/v1/files/file_XXXXXXXX \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Api-Version-Date: 2026-08-21-1"
```

```json theme={null}
{
  "object": "file",
  "id": "file_XXXXXXXX",
  "filename": "terms.pdf",
  "content_type": "application/pdf",
  "size": 82345,
  "url": "https://files.whop.com/...&signature=...",
  "removed_by_moderation": false,
  "upload_status": "ready",
  "visibility": "private",
  "created_at": "2026-08-21T18:24:00.000Z",
  "width": null,
  "height": null,
  "blurhash": null,
  "duration_seconds": null,
  "waveform_url": null
}
```

## Multipart-upload

Upload grote bestanden in delen. Whop retourneert één presigned URL per deel. Je uploadt de delen (optioneel parallel) en laat Whop ze daarna samenvoegen.

Multipart is **verplicht boven 5 GB**, omdat één uploadrequest niet groter mag zijn. Het is ook verstandig boven \~100 MB, waar één lange upload kwetsbaar is. Het bestand moet groter zijn dan 5 MB, omdat elk deel behalve het laatste minstens 5 MB moet zijn.

**1. Maak het bestand aan met multipart ingeschakeld**

Geef `multipart: true` en de totale `byte_size` mee, zodat Whop weet hoeveel presigned URL's voor delen moeten worden geretourneerd. De response bevat een `multipart_upload_id`, één presigned `url` per `part_number`, en de `multipart_chunk_size` (in bytes) die elk deel behalve het laatste moet hebben.

```bash theme={null}
curl https://api.whop.com/api/v1/files \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Api-Version-Date: 2026-08-21-1" \
  -H "Content-Type: application/json" \
  -d '{ "filename": "release.mp4", "visibility": "private", "multipart": true, "byte_size": 12582912 }'
```

```json theme={null}
{
  "object": "file",
  "id": "file_XXXXXXXX",
  "filename": "release.mp4",
  "content_type": "video/mp4",
  "size": null,
  "url": null,
  "removed_by_moderation": false,
  "upload_status": "pending",
  "visibility": "private",
  "created_at": "2026-08-21T18:24:00.000Z",
  "width": null,
  "height": null,
  "blurhash": null,
  "duration_seconds": null,
  "waveform_url": null,
  "upload_url": null,
  "upload_headers": {},
  "multipart_upload_id": "2~aBcD1234...",
  "multipart_upload_urls": [
    { "part_number": 1, "url": "https://upload.whop.com/...&part_number=1&signature=..." },
    { "part_number": 2, "url": "https://upload.whop.com/...&part_number=2&signature=..." },
    { "part_number": 3, "url": "https://upload.whop.com/...&part_number=3&signature=..." }
  ],
  "multipart_chunk_size": 5242880
}
```

> [!NOTE]
>
> Multipart-uploads ondersteunen maximaal **10.000 delen** van elk 5 MB — ongeveer 50 GB. Een `byte_size` waarvoor meer delen nodig zouden zijn, wordt geweigerd met een `400`.

**2. Upload elk deel en bewaar de ETag**

Verdeel het bestand in stukken van `multipart_chunk_size` bytes (het laatste deel mag kleiner zijn) en stuur elk stuk met `PUT` naar de `url` van het bijbehorende deel. Elke uploadresponse retourneert een **`ETag`-header** — bewaar die samen met het `part_number`, want je hebt beide nodig om af te ronden.

```javascript theme={null}
import { readFile } from "node:fs/promises";

const bytes = await readFile("./release.mp4");
const chunkSize = created.multipart_chunk_size;

const parts = await Promise.all(
  created.multipart_upload_urls.map(async ({ part_number, url }) => {
    const start = (part_number - 1) * chunkSize;
    const chunk = bytes.subarray(start, start + chunkSize);

    const res = await fetch(url, { method: "PUT", body: chunk });
    if (!res.ok) throw new Error(`Part ${part_number} failed: ${res.status}`);

    // The ETag header comes back quoted, e.g. "\"abc123\"" — send it as-is.
    return { part_number, etag: res.headers.get("etag") };
  }),
);
```

**3. Rond de upload af**

Geef de `multipart_upload_id` en het `part_number` + `etag` van elk deel door aan [Complete File Multipart Upload](https://docs.whop.com/nl/api-reference/files/complete-file-multipart-upload.md). Whop voegt de delen samen tot het uiteindelijke bestand.

```bash theme={null}
curl https://api.whop.com/api/v1/files/file_XXXXXXXX/complete \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Api-Version-Date: 2026-08-21-1" \
  -H "Content-Type: application/json" \
  -d '{
    "multipart_upload_id": "2~aBcD1234...",
    "multipart_parts": [
      { "part_number": 1, "etag": "\"5eb63bbbe01eeed093cb22bb8f5acdc3\"" },
      { "part_number": 2, "etag": "\"9e107d9d372bb6826bd81d3542a419d6\"" },
      { "part_number": 3, "etag": "\"e4d909c290d0fb1ca068ffaddf22cbd0\"" }
    ]
  }'
```

> [!WARNING]
>
> Elk deel moet op volgorde worden vermeld, met precies de `ETag` die werd geretourneerd toen je het uploadde. Een onbekende `multipart_upload_id` of een niet-overeenkomende `ETag` levert een `400` op — upload het betreffende deel opnieuw en rond opnieuw af.

**4. Poll totdat het bestand klaar is**

Haal, net als bij uploads in één deel, het bestand op totdat `upload_status` `ready` is. De ID kan dan worden gekoppeld.

## Een zichtbaarheid kiezen

Je stelt `visibility` in bij het aanmaken en kunt die daarna niet meer wijzigen:

| Zichtbaarheid | `url` die je krijgt | Gebruik voor |
| - | - | - |
| `private` (standaard) | Ondertekende URL die verloopt | Juridische documenten, bewijs bij geschillen, uploads van gebruikers |
| `public` | Permanente, niet-ondertekende CDN-URL | Productafbeeldingen, thumbnails, branding, marketingmateriaal |

Openbare bestanden worden gecachet op het CDN van Whop en kunnen niet worden ingetrokken, dus houd de standaardwaarde `private` aan voor alles wat gevoelig is. Zie [Bestanden uploaden](https://docs.whop.com/nl/developer/guides/upload-files.md#accessing-private-files) voor meer informatie.

## Een geüpload bestand gebruiken

Zodra een bestand `ready` is, geef je de `id` mee overal waar Whop een document accepteert — bijvoorbeeld als bewijs bij een [geschil](https://docs.whop.com/nl/api-reference/disputes/dispute) of als juridisch document van een account.

## Volgende stappen

> [card] [Bestanden uploaden (SDK)](https://docs.whop.com/nl/developer/guides/upload-files.md)
>
> Hoe de methoden `files.create` en `files.retrieve` van de SDK deze flow omhullen.

> [card] [Create File](https://docs.whop.com/nl/api-reference/files/create-file.md)
>
> Volledige referentie voor request en response van het create-endpoint.

> [card] [Complete File Multipart Upload](https://docs.whop.com/nl/api-reference/files/complete-file-multipart-upload.md)
>
> Referentie voor het samenvoegen van multipart-delen.

> [card] [API-versies](https://docs.whop.com/nl/developer/api/versioning.md)
>
> Waarom de header `Api-Version-Date` belangrijk is en hoe je die vastlegt.


## Related topics

- [Bestanden uploaden](https://docs.whop.com/nl/developer/guides/upload-files.md)
- [Files API](https://docs.whop.com/nl/api-reference/files/file.md)
- [Een bountyprogramma uitvoeren](https://docs.whop.com/nl/developer/bounties/run-a-bounty-program.md)
