> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tela.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Variables and files

> Fill the variables of a Canvas with text, file URLs, base64 content or files uploaded to Tela

[Variables](https://docs.tela.com/en/craft/using-variables.md) 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](https://mintcdn.com/meistrari/jZ7VrspVjrdqJJQA/images/guides/integrating-api/variables-focus.png?fit=max\&auto=format\&n=jZ7VrspVjrdqJJQA\&q=85\&s=e2aba5cd4f1365efffb32135c9f15096)

## Text

A text variable takes a plain string.

```typescript TypeScript Tela SDK theme={null}
variables: {
    document: 'Document content',
},
```

```python Python Tela SDK theme={null}
variables={
    "document": "Document content",
}
```

```json HTTP body theme={null}
"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). |

```json File URL theme={null}
"variables": {
    "document": {
        "file_url": "https://www.wmaccess.com/downloads/sample-invoice.pdf"
    }
}
```

```json Base64 theme={null}
"variables": {
    "document": {
        "file_url": "data:application/pdf;base64,JVBERi0xLjUKJeLjz9MKNCAwIG9ia..."
    }
}
```

```json Uploaded file theme={null}
"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](https://docs.tela.com/en/supported-file-formats.md).

### 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.

```typescript TypeScript Tela SDK theme={null}
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')),
    },
})
```

```javascript JavaScript Tela SDK theme={null}
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')),
    },
})
```

```python Python Tela SDK theme={null}
# 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.

```typescript TypeScript Tela SDK theme={null}
variables: {
    documents: [
        { file_url: 'https://example.com/file1.pdf' },
        { file_url: 'https://example.com/file2.pdf' },
        { file_url: 'vault://550e8400-e29b-41d4-a716-446655440000' },
    ],
},
```

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

```json HTTP body theme={null}
"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](https://docs.tela.com/api-reference/introduction.md#compatibility-date)).

**1. Request an upload URL**

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

```sh cURL theme={null}
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" }'
```

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

**2. 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.

```sh cURL theme={null}
curl -X PUT "UPLOAD_URL_FROM_PREVIOUS_STEP" \
    -H 'Content-Type: application/pdf' \
    --data-binary @sample-invoice.pdf
```

**3. Reference it in the completion**

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

```json HTTP body theme={null}
"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)](https://docs.tela.com/api-reference/file/upload.md).

> [!NOTE]
>
> 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](https://docs.tela.com/api-reference/file/create.md). 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](https://docs.tela.com/en/completion-api/async-and-webhooks.md#listing-past-runs), `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"`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.