Files

Create File

Changed on

Creates a file and returns a presigned destination to upload its bytes to. PUT the bytes to upload_url (single-part), or to each of multipart_upload_urls and then call Complete File Multipart Upload. Once the bytes land the file becomes ready, and its ID can be attached wherever a file is accepted — account legal documents, dispute evidence documents. For a step-by-step walkthrough of single-part and multipart uploads, see the direct file uploads guide.

post/files

Request

  • Base URL: https://api.whop.com/api/v1
  • URL: https://api.whop.com/api/v1/files
  • Auth: HTTP bearer

Headers

Idempotency-Keystring
Example:d9105228-4a08-46b1-8b91-42fed586d383

A unique key that makes this request safe to retry. See Idempotent requests.

Request body

byte_sizeinteger

The file's size in bytes. Required when multipart is true. Multipart uploads support at most 10,000 parts of 5MB each (about 50 GB).

filenamestring required

The name of the file including its extension, e.g. terms.pdf.

multipartboolean

Upload the file in 5MB parts. Required for files larger than 5GB; useful above ~100MB. The file must be larger than 5MB.

visibility'public' | 'private'

public files are served via an unsigned CDN URL — use for assets anyone may see. private files are served via a signed, expiring URL — use for sensitive documents. Defaults to private.

Example request

{
  "byte_size": 15728640,
  "filename": "terms.pdf",
  "multipart": true,
  "visibility": "public"
}

Response

file created with a single-part upload destination

blurhashstring nullable required

BlurHash placeholder for an image or video. Null when unavailable or removed by moderation.

content_typestring nullable required

The original file's MIME type, preserved when removed by moderation, e.g. application/pdf.

created_atstring required

When the file was created, as an ISO 8601 timestamp.

duration_secondsnumber nullable required

Audio or video duration in seconds. Null when unavailable or removed by moderation.

filenamestring nullable required

The original filename, including its extension.

heightinteger nullable required

Image or video height in pixels. Null when unavailable or removed by moderation.

idstring required

The file's ID, prefixed file_.

multipart_chunk_sizeinteger nullable

The byte size each part (except the last) must be. Present only on create, and only for multipart uploads.

multipart_upload_idstring nullable

The ID of the multipart upload, passed back to complete. Present only on create, and only for multipart uploads.

objectstring required

The type of this object, always file.

removed_by_moderationboolean required

Whether moderation removed the file. When true, url serves a replacement image; filename, size, and content type still describe the original file.

sizeinteger nullable required

The file size in bytes. null until the upload has finished.

upload_headersobject

Headers to send with the upload PUT. Present only on create.

upload_status'pending' | 'processing' | 'ready' | 'failed' required

Where the file is in its upload lifecycle.

upload_urlstring nullable

Presigned URL to PUT the file's bytes to. Present only on create, and only for single-part uploads.

urlstring nullable required

A URL to download the file: a permanent CDN URL for public files, a signed expiring URL for private ones. Null until the upload has finished; a replacement image URL when removed by moderation.

visibility'public' | 'private' required

public files are served via an unsigned CDN URL; private files via a signed, expiring URL.

waveform_urlstring nullable required

Audio waveform URL. Null when unavailable or removed by moderation.

widthinteger nullable required

Image or video width in pixels. Null when unavailable or removed by moderation.

Example response

{
  "content_type": "application/pdf",
  "created_at": "2026-01-01T12:00:00.000Z",
  "filename": "evidence.pdf",
  "id": "file_xxxxxxxxxxxxxx",
  "multipart_chunk_size": 5242880,
  "multipart_upload_id": "upload-id",
  "multipart_upload_urls": [
    {
      "part_number": 1,
      "url": "https://whop-assets-example.s3.amazonaws.com/uploads/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/application.pdf"
    }
  ],
  "object": "file",
  "size": 9670,
  "upload_headers": {},
  "upload_status": "pending",
  "upload_url": "https://whop-assets-example.s3.amazonaws.com/uploads/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/application.pdf",
  "url": "https://whop-assets-example.s3.amazonaws.com/uploads/audio/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "visibility": "private"
}

Changes

  • 507636677fe9Revision changes
    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

  • e91d507bda45Revision changes
    • breaking

      request property was restricted to a list of enum values

    • breaking

      removed subschema #2 from the request property oneOf list

    • breaking

      the request property type changed from no type to string

    • breaking

      removed the success response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • info

      added the new optional header request parameter Api-Version-Date to all path's operations

    • info

      added the new optional header request parameter Idempotency-Key

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      request body became optional

    • info

      added the new private enum value to the request property

    • info

      added the new public enum value to the request property

    • info

      added the non-success response with the status

    • info

      removed the non-success response with the status

    • info

      removed the non-success response with the status

    • info

      removed the non-success response with the status

    • info

      removed the non-success response with the status

    • info

      removed the non-success response with the status

    • info

      added the success response with the status