POST
/
v3
/
files
cURL
curl --request POST \
  --url https://api.tela.com/v3/files \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-compatibility-date: <x-compatibility-date>' \
  --data '{
  "fileName": "test.txt"
}'
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "uploadUrl": "https://file-upload-temporary.example.com/upload?token=xyz"
}

​
File Upload Process

The v3 file upload API provides a secure two-step process for uploading files to Tela’s storage:
  1. Request an upload URL - Call the /v3/files endpoint to get a temporary upload URL
  2. Upload your file - Use the returned upload URL to upload your file content directly

​
Step 1: Get Upload URL

First, request a temporary upload URL by providing the filename: 
const response = await fetch('https://api.tela.com/v3/files', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'x-compatibility-date': '2025-07-23',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    fileName: 'test.txt'
  })
})

const { id, uploadUrl } = await response.json()
The response will include:
  • id: The unique identifier for your file
  • uploadUrl: A temporary URL to upload your file content

​
Step 2: Upload File Content

Use the uploadUrl from the previous step to upload your file content: 
// For browser environments
const file = new File(['Hello, world!'], 'test.txt', { type: 'text/plain' })

await fetch(uploadUrl, {
  method: 'PUT',
  headers: {
    'Content-Type': file.type // Explicitly set Content-Type
  },
  body: file
})

// For Node.js environments
const blob = new Blob(['Hello, world!'], { type: 'text/plain' })

await fetch(uploadUrl, {
  method: 'PUT',
  headers: {
    'Content-Type': 'text/plain'
  },
  body: blob
})
The upload URL is temporary and will expire after a short period. Make sure to upload your file promptly after receiving the URL.

​
Using the File ID

After successfully uploading your file, you can use the UUID returned in Step 1 to reference the file in other API endpoints: 
// Retrieve file metadata
const fileData = await fetch(`https://api.tela.com/v3/files/${id}`, {
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'x-compatibility-date': '2025-07-23'
  }
}).then(res => res.json())

​
Request Headers

​
Required Headers

  • Authorization: Bearer token for authentication
  • x-compatibility-date: API version compatibility date (e.g., 2025-07-23)

​
Content Types

When uploading the file content in Step 2, set the appropriate Content-Type header:
  • text/plain for text files
  • application/json for JSON files
  • image/png, image/jpeg for images
  • application/pdf for PDF files
  • And other standard MIME types as needed
While some HTTP clients may attempt to infer the Content-Type from the file, it’s best practice to explicitly set the Content-Type header to ensure proper file handling. This is especially important for binary files and when the file extension doesn’t match the actual content type.

​
Complete Example

Here’s a complete example showing the entire file upload process: 
async function uploadFile(file: File) {
  // Step 1: Get upload URL
  const response = await fetch('https://api.tela.com/v3/files', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN',
      'x-compatibility-date': '2025-07-23',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ fileName: file.name })
  })

  const { id, uploadUrl } = await response.json()
  console.log(`File ID: ${id}`) // e.g., 3fa85f64-5717-4562-b3fc-2c963f66afa6

  // Step 2: Upload file content
  await fetch(uploadUrl, {
    method: 'PUT',
    headers: {
      'Content-Type': file.type || 'application/octet-stream'
    },
    body: file
  })

  console.log('File uploaded successfully!')
  return id
}

// Usage - Browser
const file = new File(['Hello, world!'], 'test.txt', { type: 'text/plain' })
const fileId = await uploadFile(file)

// Usage - From file input
const fileInput = document.querySelector('input[type="file"]') as HTMLInputElement
if (fileInput.files?.[0]) {
  const fileId = await uploadFile(fileInput.files[0])
}

​
Using Uploaded Files in Completions

After uploading files, you can use them in your canvas completions with the vault:// URL scheme: 
// Using a single uploaded file
const completion = await tela.completions.create({
  canvasId: process.env.TELA_CANVAS_ID,
  variables: {
    document: { file_url: `vault://3fa85f64-5717-4562-b3fc-2c963f66afa6` }
  }
})

// Using multiple uploaded files
const completion2 = await tela.completions.create({
  canvasId: process.env.TELA_CANVAS_ID,
  variables: {
    documents: [
      { file_url: `vault://3fa85f64-5717-4562-b3fc-2c963f66afa6` },
      { file_url: `vault://550e8400-e29b-41d4-a716-446655440000` },
      { file_url: 'https://example.com/public-file.pdf' } // Mix vault and public URLs
    ]
  }
})
The vault:// URL scheme provides secure access to your uploaded files. These URLs can only be accessed within your workspace context and are ideal for processing sensitive documents.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
x-compatibility-date
string<date>
required

API version compatibility date (e.g., 2025-07-23)

Body

application/json
​
fileName
string
required

The name of the file to upload

Response

Successful creation of upload URL

​
id
string
required

Unique identifier for the uploaded file

​
uploadUrl
string
required

Temporary URL to upload the file content