Variables and files

Variables are the inputs of a Canvas. In a request they go in the variables object, keyed by the variable name exactly as it appears in the Canvas. Each value is either a text or a file. The Connect via API dialog generates the snippet with the variables of the Canvas already in place, so you only fill in the values.

Snippet with the variables of the Canvas

Text

A text variable takes a plain string.

variables: {
    document: 'Document content',
},

variables={
    "document": "Document content",
}

"variables": {
    "document": "Document content"
}

Files

A file variable takes an object with a file_url. The URL can point to three kinds of content:

`file_url`	When to use it
`https://…`	The file is already reachable on the internet, such as a document in your own storage.
`data:<mime type>;base64,…`	The file is in memory and small enough to send inline.
`vault://<file id>`	You uploaded the file to Tela first with the file endpoints (see below).

"variables": {
    "document": {
        "file_url": "https://www.wmaccess.com/downloads/sample-invoice.pdf"
    }
}

"variables": {
    "document": {
        "file_url": "data:application/pdf;base64,JVBERi0xLjUKJeLjz9MKNCAwIG9ia..."
    }
}

"variables": {
    "document": {
        "file_url": "vault://3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
}

The accepted formats (PDF, images, audio, video, Office documents, CSV and plain text) are listed in Supported file formats.

With the SDKs

The SDKs wrap the file for you: tela.createFile (TypeScript and JavaScript) and client.create_file (Python) accept a URL and build the file_url object. createFile also accepts a Buffer, a Blob or a readable stream, and create_file accepts an open file, so you can send local files without encoding them yourself.

import fs from 'node:fs'
import type { TelaFile } from '@meistrari/tela-sdk-js'

const completion = await tela.completions.create<{ document: TelaFile }, { fileSummary: string }>({
    canvasId: process.env.TELA_CANVAS_ID,
    variables: {
        // A URL...
        document: tela.createFile('https://www.wmaccess.com/downloads/sample-invoice.pdf'),
        // ...or a local file
        // document: tela.createFile(fs.createReadStream('./sample-invoice.pdf')),
    },
})

import fs from 'node:fs'

const completion = await tela.completions.create({
    canvasId: process.env.TELA_CANVAS_ID,
    variables: {
        // A URL...
        document: tela.createFile('https://www.wmaccess.com/downloads/sample-invoice.pdf'),
        // ...or a local file
        // document: tela.createFile(fs.createReadStream('./sample-invoice.pdf')),
    },
})

# A URL...
completion = client.completions.create(
    canvas_id=TELA_CANVAS_ID,
    variables={
        "document": client.create_file("https://www.wmaccess.com/downloads/sample-invoice.pdf"),
    },
)

# ...or a local file
with open("./sample-invoice.pdf", "rb") as file:
    completion = client.completions.create(
        canvas_id=TELA_CANVAS_ID,
        variables={
            "document": client.create_file(file),
        },
    )

Several files in one variable

A variable can receive an array of file objects. You can mix public and uploaded files in the same array.

variables: {
    documents: [
        { file_url: 'https://example.com/file1.pdf' },
        { file_url: 'https://example.com/file2.pdf' },
        { file_url: 'vault://550e8400-e29b-41d4-a716-446655440000' },
    ],
},

variables={
    "documents": [
        {"file_url": "https://example.com/file1.pdf"},
        {"file_url": "https://example.com/file2.pdf"},
        {"file_url": "vault://550e8400-e29b-41d4-a716-446655440000"},
    ],
}

"variables": {
    "documents": [
        { "file_url": "https://example.com/file1.pdf" },
        { "file_url": "https://example.com/file2.pdf" },
        { "file_url": "vault://550e8400-e29b-41d4-a716-446655440000" }
    ]
}

Uploading a file first

When a file is not public and too large to inline, upload it to Tela and reference it by ID. The upload is a two-step process with POST /v3/files, which requires the x-compatibility-date header (see Compatibility date).

Request an upload URL

Send the file name. The response has the file id and a temporary uploadUrl.

cURL

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

Response

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

Upload the content

PUT the bytes to uploadUrl, setting the Content-Type of the file. The URL expires after a short period, so upload right away.

cURL

curl -X PUT "UPLOAD_URL_FROM_PREVIOUS_STEP" \
    -H 'Content-Type: application/pdf' \
    --data-binary @sample-invoice.pdf

Reference it in the completion

Use vault://<id> as the file_url of the variable. The file can only be read inside your Workspace.

HTTP body

"variables": {
    "document": { "file_url": "vault://3fa85f64-5717-4562-b3fc-2c963f66afa6" }
}

GET /v3/files/{id} returns the metadata of an uploaded file (fileName, size, mimeType, createdAt and a url). The full walkthrough, with TypeScript and Python examples, is in Upload a File (v3).

The older POST /v2/file endpoint also returns an upload_url to PUT the file to, together with a download_url you can pass as a regular file_url. See Upload a File. New integrations should use /v3/files.

Where the files show up afterwards

Every run records its inputs. In the result of an asynchronous run and in the completion run history, input_content.variables holds the values you sent and input_content.files lists each file with its name (the variable name), url and used_at: "variables".

Get started

Build

Test

Operate

Integrate

Variables and files

Text

Files

With the SDKs

Several files in one variable

Uploading a file first

Where the files show up afterwards

​Text

​Files

​With the SDKs

​Several files in one variable

​Uploading a file first

​Where the files show up afterwards

Text

Files

With the SDKs

Several files in one variable

Uploading a file first

Where the files show up afterwards