Sign in
Files

Create File

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

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

content_typestring nullable required

The file's MIME type, e.g. application/pdf.

created_atstring required

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

filenamestring nullable required

The original filename, including its extension.

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.

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.

visibility'public' | 'private' required

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

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

Changed in 1 of the 74 revisions of this API.4214

  • e91d507bda454214See the full diff
    • ▲

      request property was restricted to a list of enum values

      request-property-became-enum

    • ▲

      removed subschema #2 from the request property oneOf list

      request-property-one-of-removed

    • ▲

      the request property type changed from no type to string

      request-property-type-changed

    • ▲

      removed the success response with the status

      response-success-status-removed

    • ●

      removed the optional property / from the response with the status

      response-optional-property-removed

    • ●

      removed the optional property / from the response with the status

      response-optional-property-removed

    • ○

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

      new-optional-request-default-parameter-to-existing-path

    • ○

      added the new optional header request parameter Idempotency-Key

      new-optional-request-parameter

    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      request body became optional

      request-body-became-optional

    • ○

      added the new private enum value to the request property

      request-property-enum-value-added

    • ○

      added the new public enum value to the request property

      request-property-enum-value-added

    • ○

      added the non-success response with the status

      response-non-success-status-added

    • ○

      removed the non-success response with the status

      response-non-success-status-removed

    • ○

      removed the non-success response with the status

      response-non-success-status-removed

    • ○

      removed the non-success response with the status

      response-non-success-status-removed

    • ○

      removed the non-success response with the status

      response-non-success-status-removed

    • ○

      removed the non-success response with the status

      response-non-success-status-removed

    • ○

      added the success response with the status

      response-success-status-added

Of the 74 revisions, 1 has no diff computed.