Upload a File (v3)

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"
}
'

import requests

url = "https://api.tela.com/v3/files"

payload = { "fileName": "test.txt" }
headers = {
    "x-compatibility-date": "<x-compatibility-date>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-compatibility-date': '<x-compatibility-date>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({fileName: 'test.txt'})
};

fetch('https://api.tela.com/v3/files', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tela.com/v3/files",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'fileName' => 'test.txt'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-compatibility-date: <x-compatibility-date>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tela.com/v3/files"

	payload := strings.NewReader("{\n  \"fileName\": \"test.txt\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-compatibility-date", "<x-compatibility-date>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.tela.com/v3/files")
  .header("x-compatibility-date", "<x-compatibility-date>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"fileName\": \"test.txt\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.tela.com/v3/files")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-compatibility-date"] = '<x-compatibility-date>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"fileName\": \"test.txt\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "uploadUrl": "https://file-upload-temporary.example.com/upload?token=xyz"
}

POST

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"
}
'

import requests

url = "https://api.tela.com/v3/files"

payload = { "fileName": "test.txt" }
headers = {
    "x-compatibility-date": "<x-compatibility-date>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-compatibility-date': '<x-compatibility-date>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({fileName: 'test.txt'})
};

fetch('https://api.tela.com/v3/files', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tela.com/v3/files",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'fileName' => 'test.txt'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-compatibility-date: <x-compatibility-date>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tela.com/v3/files"

	payload := strings.NewReader("{\n  \"fileName\": \"test.txt\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-compatibility-date", "<x-compatibility-date>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.tela.com/v3/files")
  .header("x-compatibility-date", "<x-compatibility-date>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"fileName\": \"test.txt\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.tela.com/v3/files")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-compatibility-date"] = '<x-compatibility-date>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"fileName\": \"test.txt\"\n}"

response = http.request(request)
puts response.read_body

{
  "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:

Request an upload URL - Call the /v3/files endpoint to get a temporary upload URL
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()

import requests

response = requests.post(
  'https://api.tela.com/v3/files',
  headers={
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'x-compatibility-date': '2025-07-23'
  },
  json={
    'fileName': 'test.txt'
  }
)

data = response.json()
file_id = data['id']
upload_url = data['uploadUrl']

curl -X POST https://api.tela.com/v3/files \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-compatibility-date: 2025-07-23" \
  -H "Content-Type: application/json" \
  -d '{"fileName": "test.txt"}'

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
})

# For file upload
with open('test.txt', 'rb') as file:
    requests.put(
        upload_url,
        headers={
            'Content-Type': 'text/plain'  # Explicitly set Content-Type
        },
        data=file
    )

# For in-memory content
import io
file_content = b'Hello, world!'
file_like = io.BytesIO(file_content)

requests.put(
    upload_url,
    headers={
        'Content-Type': 'text/plain'
    },
    data=file_like
)

# Upload a file
curl -X PUT "UPLOAD_URL_FROM_PREVIOUS_STEP" \
  -H "Content-Type: text/plain" \
  --data-binary @test.txt

# Or upload binary content
curl -X PUT "UPLOAD_URL_FROM_PREVIOUS_STEP" \
  -H "Content-Type: application/pdf" \
  --data-binary @document.pdf

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())

# Retrieve file metadata
response = requests.get(
  f'https://api.tela.com/v3/files/{file_id}',
  headers={
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'x-compatibility-date': '2025-07-23'
  }
)
file_data = response.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])
}

import requests
import mimetypes

def upload_file(file_path):
    # Step 1: Get upload URL
    file_name = file_path.split('/')[-1]
    response = requests.post(
        'https://api.tela.com/v3/files',
        headers={
            'Authorization': 'Bearer YOUR_API_TOKEN',
            'x-compatibility-date': '2025-07-23'
        },
        json={'fileName': file_name}
    )
    
    data = response.json()
    file_id = data['id']  # e.g., 3fa85f64-5717-4562-b3fc-2c963f66afa6
    upload_url = data['uploadUrl']
    print(f'File ID: {file_id}')
    
    # Step 2: Upload file content
    content_type, _ = mimetypes.guess_type(file_path)
    if not content_type:
        content_type = 'application/octet-stream'
    
    with open(file_path, 'rb') as file:
        requests.put(
            upload_url,
            headers={'Content-Type': content_type},
            data=file
        )
    
    print('File uploaded successfully!')
    return file_id

# Usage
file_id = upload_file('test.txt')

# Or with in-memory content
import io
def upload_bytes(file_name, content_bytes, content_type='application/octet-stream'):
    # ... (Step 1 same as above)
    
    requests.put(
        upload_url,
        headers={'Content-Type': content_type},
        data=io.BytesIO(content_bytes)
    )
    return file_id

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
    ]
  }
})

# Using a single uploaded file
completion = client.completions.create(
    canvas_id=TELA_CANVAS_ID,
    variables={
        "document": {"file_url": f"vault://3fa85f64-5717-4562-b3fc-2c963f66afa6"}
    }
)

# Using multiple uploaded files
completion2 = client.completions.create(
    canvas_id=TELA_CANVAS_ID,
    variables={
        "documents": [
            {"file_url": f"vault://3fa85f64-5717-4562-b3fc-2c963f66afa6"},
            {"file_url": f"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

string

required

Unique identifier for the uploaded file

uploadUrl

string

required

Temporary URL to upload the file content

Completion

File

Test Case

Prompt Version

Task

Upload a File (v3)

File Upload Process

Step 1: Get Upload URL

Step 2: Upload File Content

Using the File ID

Request Headers

Required Headers

Content Types

Complete Example

Using Uploaded Files in Completions

Authorizations

Headers

Body

Response

​File Upload Process

​Step 1: Get Upload URL

​Step 2: Upload File Content

​Using the File ID

​Request Headers

​Required Headers

​Content Types

​Complete Example

​Using Uploaded Files in Completions

Authorizations

Headers

Body

Response

File Upload Process

Step 1: Get Upload URL

Step 2: Upload File Content

Using the File ID

Request Headers

Required Headers

Content Types

Complete Example

Using Uploaded Files in Completions