File uploads

Upload files using various methods and formats

The Cloudflare SDK supports multiple file upload methods to accommodate different runtime environments and use cases.

Supported file types

Request parameters that accept file uploads support multiple formats:

File API

Web-standard File objects or compatible structures

ReadStream

Node.js fs.ReadStream for file system access

Response

fetch Response objects or compatible structures

toFile Helper

SDK’s toFile() helper for buffers and arrays

File upload methods

ReadStream (Node.js)

Use fs.createReadStream() for optimal performance in Node.js:

import fs from 'fs';
import Cloudflare from 'cloudflare';

const client = new Cloudflare();

await client.apiGateway.userSchemas.create({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
  file: fs.createReadStream('/path/to/schema.json'),
  kind: 'openapi_v3',
});

This is the recommended approach for Node.js environments as it streams the file without loading it entirely into memory.

File API (Browser)

Use the web File API in browser environments:

import Cloudflare from 'cloudflare';

const client = new Cloudflare();

// From a File input
const fileInput = document.querySelector('input[type="file"]');
const file = fileInput.files[0];

await client.apiGateway.userSchemas.create({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
  file: file,
  kind: 'openapi_v3',
});

// Or create a File manually
await client.apiGateway.userSchemas.create({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
  file: new File(['my bytes'], 'schema.json', { type: 'application/json' }),
  kind: 'openapi_v3',
});

Fetch Response

Pass a fetch Response object directly:

import fetch from 'node-fetch';
import Cloudflare from 'cloudflare';

const client = new Cloudflare();

await client.apiGateway.userSchemas.create({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
  file: await fetch('https://example.com/schema.json'),
  kind: 'openapi_v3',
});

This is useful for proxying files from other services.

toFile Helper

Use the toFile() helper for buffers and typed arrays:

import Cloudflare, { toFile } from 'cloudflare';

const client = new Cloudflare();

// From a Buffer
await client.apiGateway.userSchemas.create({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
  file: await toFile(Buffer.from('my bytes'), 'schema.json'),
  kind: 'openapi_v3',
});

// From a Uint8Array
await client.apiGateway.userSchemas.create({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
  file: await toFile(new Uint8Array([0, 1, 2]), 'schema.json'),
  kind: 'openapi_v3',
});

The toFile helper

The toFile() helper converts raw data into an uploadable format:

import { toFile } from 'cloudflare';

// Signature
toFile(
  data: Buffer | Uint8Array | ArrayBuffer,
  filename: string,
  options?: { type?: string }
): Promise<File>

Usage examples

Buffer

import { toFile } from 'cloudflare';

const file = await toFile(
  Buffer.from('file contents'),
  'document.txt',
  { type: 'text/plain' }
);

import { toFile } from 'cloudflare';

const bytes = new Uint8Array([72, 101, 108, 108, 111]);
const file = await toFile(bytes, 'data.bin');

import { toFile } from 'cloudflare';

const buffer = new ArrayBuffer(8);
const file = await toFile(buffer, 'data.bin');

data · Buffer | Uint8Array | ArrayBuffer · required

Raw binary data to upload

filename · string · required

Name for the uploaded file

options.type · string

MIME type of the file (e.g., "application/json")

Reading files from disk

Use fileFromPath() to read files from the filesystem:

import { fileFromPath } from 'cloudflare';

const file = await fileFromPath('/path/to/schema.json');

await client.apiGateway.userSchemas.create({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
  file: file,
  kind: 'openapi_v3',
});

fileFromPath() is only available in Node.js environments.

Complete upload examples

API Gateway schema upload

import fs from 'fs';
import Cloudflare from 'cloudflare';

const client = new Cloudflare({
  apiToken: process.env.CLOUDFLARE_API_TOKEN,
});

// Upload OpenAPI schema from file system
const schema = await client.apiGateway.userSchemas.create({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
  file: fs.createReadStream('./openapi.yaml'),
  kind: 'openapi_v3',
});

console.log('Schema uploaded:', schema.schema_id);

Dynamic file generation

import Cloudflare, { toFile } from 'cloudflare';

const client = new Cloudflare();

// Generate schema programmatically
const schemaData = {
  openapi: '3.0.0',
  info: {
    title: 'My API',
    version: '1.0.0',
  },
  paths: {},
};

const schemaJson = JSON.stringify(schemaData, null, 2);
const file = await toFile(
  Buffer.from(schemaJson),
  'schema.json',
  { type: 'application/json' }
);

await client.apiGateway.userSchemas.create({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
  file: file,
  kind: 'openapi_v3',
});

Remote file upload

import fetch from 'node-fetch';
import Cloudflare from 'cloudflare';

const client = new Cloudflare();

// Download and upload in one step
const remoteFile = await fetch('https://api.example.com/schema.json');

await client.apiGateway.userSchemas.create({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
  file: remoteFile,
  kind: 'openapi_v3',
});

Multipart form data

File uploads use multipart/form-data encoding automatically:

// The SDK handles multipart encoding for you
await client.apiGateway.userSchemas.create({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
  file: fs.createReadStream('./schema.json'),
  kind: 'openapi_v3',
  // Other fields are encoded alongside the file
});

The SDK automatically sets the correct Content-Type: multipart/form-data header and constructs the multipart body.

File metadata

When using the File API or toFile(), you can specify metadata:

// Using File constructor
const file = new File(
  ['content'],
  'filename.txt',
  {
    type: 'text/plain',
    lastModified: Date.now(),
  }
);

// Using toFile helper
const file = await toFile(
  Buffer.from('content'),
  'filename.txt',
  { type: 'text/plain' }
);

Best practices

1. Use streams for large files

   In Node.js, prefer fs.createReadStream() to avoid loading entire files into memory:

   // Good: Streams the file
   file: fs.createReadStream('/large/file.json')
   
   // Bad: Loads entire file into memory
   file: await toFile(fs.readFileSync('/large/file.json'), 'file.json')
   
2. Set correct MIME types

   Specify the correct content type for better compatibility:

   const file = await toFile(
     jsonBuffer,
     'schema.json',
     { type: 'application/json' }
   );
   
3. Handle file errors

   Wrap file operations in try-catch blocks:

   try {
     const file = fs.createReadStream('/path/to/file');
     await client.apiGateway.userSchemas.create({
       zone_id: zoneId,
       file,
       kind: 'openapi_v3',
     });
   } catch (err) {
     if (err.code === 'ENOENT') {
       console.error('File not found');
     }
     throw err;
   }
   
4. Validate files before upload

   Check file size and format before initiating uploads:

   const stats = fs.statSync('/path/to/file');
   if (stats.size > 10 * 1024 * 1024) {
     throw new Error('File too large (max 10MB)');
   }
   

TypeScript types

The SDK provides type definitions for uploadable values:

type Uploadable = 
  | File
  | Blob  
  | Response
  | ReadStream
  | { 
      name?: string;
      type?: string;
      size?: number;
      arrayBuffer(): Promise<ArrayBuffer>;
    };

Any object matching this structure can be used for file uploads.