> ## 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.
# Run Canvas
> Executes a canvas
## Files
The Tela SDKs allows you to easily process files, such as PDFs, by creating a completion. You can use various file sources including public URLs, vault URLs from uploaded files, or pass multiple files in a single variable.
When passing file URLs directly (without using the SDK's `.createFile()` method), you must wrap them in an object with a `file_url` property. The `.createFile()` method handles this formatting automatically.
### Single File Processing
Below is an example of processing a single PDF document:
```typescript typescript theme={null}
import { createTelaClient } from '@meistrari/tela-sdk-js'
import type { TelaFile } from '@meistrari/tela-sdk-js'
const tela = createTelaClient({
apiKey: process.env.TELA_API_KEY,
})
const completion = await tela.completions.create<{ document: TelaFile }, { fileSummary: string }>({
canvasId: process.env.TELA_CANVAS_ID,
variables: {
document: tela.createFile('https://www.wmaccess.com/downloads/sample-invoice.pdf'), // It is possible to pass a URL, Buffer, Blob, etc.
},
})
```
```javascript javascript theme={null}
import { createTelaClient } from '@meistrari/tela-sdk-js'
import type { TelaFile } from '@meistrari/tela-sdk-js'
const tela = createTelaClient({
apiKey: process.env.TELA_API_KEY,
})
const completion = await tela.completions.create({
canvasId: process.env.TELA_CANVAS_ID,
variables: {
document: tela.createFile('https://www.wmaccess.com/downloads/sample-invoice.pdf'), // It is possible to pass a URL, Buffer, Blob, etc.
},
})
```
```python python theme={null}
import os
from tela import create_tela_client
TELA_CANVAS_ID = os.getenv("TELA_CANVAS_ID")
TELA_API_KEY = os.getenv("TELA_API_KEY")
client = create_tela_client(
api_key=TELA_API_KEY,
)
completion = client.completions.create(
canvas_id=TELA_CANVAS_ID,
variables={
"document": client.create_file("https://www.wmaccess.com/downloads/sample-invoice.pdf"),
},
)
```
### Using Vault URLs
After uploading a file using the `/v3/files` endpoint, you can use the vault URL in your completions. When not using the SDK's `.createFile()` method, you need to wrap the URL in an object with a `file_url` property:
```typescript typescript theme={null}
// First, upload a file and get the file ID
const fileId = '3fa85f64-5717-4562-b3fc-2c963f66afa6' // UUID from file upload
const completion = await tela.completions.create({
canvasId: process.env.TELA_CANVAS_ID,
variables: {
document: { file_url: `vault://${fileId}` }, // Using vault:// URL as object
},
})
```
```javascript javascript theme={null}
// First, upload a file and get the file ID
const fileId = '3fa85f64-5717-4562-b3fc-2c963f66afa6' // UUID from file upload
const completion = await tela.completions.create({
canvasId: process.env.TELA_CANVAS_ID,
variables: {
document: { file_url: `vault://${fileId}` }, // Using vault:// URL as object
},
})
```
```python python theme={null}
# First, upload a file and get the file ID
file_id = '3fa85f64-5717-4562-b3fc-2c963f66afa6' # UUID from file upload
completion = client.completions.create(
canvas_id=TELA_CANVAS_ID,
variables={
"document": {"file_url": f"vault://{file_id}"}, # Using vault:// URL as object
},
)
```
### Multiple Files in a Single Variable
You can pass multiple file URLs in a single variable as an array:
```typescript typescript theme={null}
const completion = await tela.completions.create({
canvasId: process.env.TELA_CANVAS_ID,
variables: {
documents: [
{ file_url: 'https://example.com/file1.pdf' },
{ file_url: 'https://example.com/file2.pdf' },
{ file_url: 'vault://550e8400-e29b-41d4-a716-446655440000' }, // Mix of public and vault URLs
],
},
})
```
```javascript javascript theme={null}
const completion = await tela.completions.create({
canvasId: process.env.TELA_CANVAS_ID,
variables: {
documents: [
{ file_url: 'https://example.com/file1.pdf' },
{ file_url: 'https://example.com/file2.pdf' },
{ file_url: 'vault://550e8400-e29b-41d4-a716-446655440000' }, // Mix of public and vault URLs
],
},
})
```
```python python theme={null}
completion = client.completions.create(
canvas_id=TELA_CANVAS_ID,
variables={
"documents": [
{"file_url": "https://example.com/file1.pdf"},
{"file_url": "https://example.com/file2.pdf"},
{"file_url": "vault://550e8400-e29b-41d4-a716-446655440000"}, # Mix of public and vault URLs
],
},
)
```
## Streaming
The Tela SDKs provides a `stream` option, which allows you to consume the stream of the completion. Below is an example of consuming a stream of the completion.
```typescript typescript theme={null}
import fs from 'node:fs'
import { createTelaClient } from '@meistrari/tela-sdk-js'
import type { TelaFile } from '@meistrari/tela-sdk-js'
const tela = createTelaClient({
apiKey: process.env.TELA_API_KEY,
})
const PATH = 'examples/stream/sample-invoice.pdf'
const fileStream = fs.createReadStream(PATH)
const completion = await tela.completions.create<{ document: TelaFile }, { fileSummary: string }>({
canvasId: process.env.TELA_CANVAS_ID,
variables: {
document: tela.createFile(fileStream),
},
stream: true,
})
for await (const chunk of completion) {
console.log(JSON.stringify(chunk))
}
```
```javascript javascript theme={null}
import fs from 'node:fs'
import { createTelaClient } from '@meistrari/tela-sdk-js'
import type { TelaFile } from '@meistrari/tela-sdk-js'
const tela = createTelaClient({
apiKey: process.env.TELA_API_KEY,
})
const PATH = 'examples/stream/sample-invoice.pdf'
const fileStream = fs.createReadStream(PATH)
const completion = await tela.completions.create({
canvasId: process.env.TELA_CANVAS_ID,
variables: {
document: tela.createFile(fileStream),
},
stream: true,
})
for await (const chunk of completion) {
console.log(JSON.stringify(chunk))
}
```
```python python theme={null}
import os
from tela import create_tela_client
TELA_CANVAS_ID = os.getenv("TELA_CANVAS_ID")
TELA_API_KEY = os.getenv("TELA_API_KEY")
client = create_tela_client(
api_key=TELA_API_KEY,
)
PATH = 'examples/stream/sample-invoice.pdf'
with open(PATH, 'rb') as file:
completion = client.completions.create(
canvas_id=TELA_CANVAS_ID,
variables={
"document": client.create_file(file),
},
stream=True,
)
for chunk in completion:
print(chunk)
```
## Webhook
The Tela SDKs provides a `webhookUrl` option, which allows you to receive a webhook when the completion is finished. Below is an example of receiving a webhook when the completion is finished.
```typescript typescript theme={null}
import { createTelaClient } from '@meistrari/tela-sdk-js'
const tela = createTelaClient({
apiKey: process.env.TELA_API_KEY,
})
const webhook = await tela.completions.create({
canvasId: process.env.TELA_CANVAS_ID,
variables: {
document: tela.createFile('https://www.wmaccess.com/downloads/sample-invoice.pdf'),
},
webhookUrl: 'https://webhook.site/12345',
})
```
```javascript javascript theme={null}
import { createTelaClient } from '@meistrari/tela-sdk-js'
const tela = createTelaClient({
apiKey: process.env.TELA_API_KEY,
})
const webhook = await tela.completions.create({
canvasId: process.env.TELA_CANVAS_ID,
variables: {
document: tela.createFile('https://www.wmaccess.com/downloads/sample-invoice.pdf'),
},
webhookUrl: 'https://webhook.site/12345',
})
```
```python python theme={null}
import os
from tela import create_tela_client
TELA_CANVAS_ID = os.getenv("TELA_CANVAS_ID")
TELA_API_KEY = os.getenv("TELA_API_KEY")
client = create_tela_client(
api_key=TELA_API_KEY,
)
webhook = client.completions.create(
canvas_id=TELA_CANVAS_ID,
variables={
"document": client.create_file("https://www.wmaccess.com/downloads/sample-invoice.pdf"),
},
webhook_url="https://webhook.site/12345",
)
print(webhook)
```
For detailed information about the webhook payload structure, see the [Webhook Payload Structure](/en/completion-api-guide#webhook-payload-structure) section in the completion API guide.
## OpenAPI
````yaml POST /v2/chat/completions
openapi: 3.0.1
info:
title: Tela API
license:
name: MIT
version: 1.0.0
servers:
- url: https://api.tela.com
security: []
paths:
/v2/chat/completions:
post:
requestBody:
description: The canvas to execute
content:
application/json:
schema:
$ref: '#/components/schemas/ChatCompletionRequest'
required: true
responses:
'200':
description: Successful completions
content:
application/json:
schema:
$ref: '#/components/schemas/ChatCompletionResponses'
examples:
Plain Text:
value:
id: crsv-i52z8vnqekc
object: chat.completion
created: 1728399621
choices:
- message:
role: assistant
content:
text: >-
The content of the PDF is not provided, so a
summary cannot be generated.
With Output Format:
value:
id: crsv-i52z8vnqekc
object: chat.completion
created: 1728399621
choices:
- message:
role: assistant
content:
rationale: >-
The content of the PDF is not provided, so a
summary cannot be generated.
message: No summary can be generated.
With Webhook:
value:
id: b83b1558-de5b-4e45-b517-7bececbdd154
status: created
inputContent:
files: []
messages: []
variables: null
outputContent: null
rawInput:
canvas_id: 95cec438-6080-44fe-8275-28b16bd40178
variables: {}
webhook_url: https://your-webhook-url.com
rawOutput: null
compatibilityDate: '2024-10-14T00:00:00.000Z'
promptVersionId: 76065caa-c519-441a-8fe2-cc43e29664ab
promptApplicationId: null
workspaceId: 3f55cfd9-4427-4887-a181-d9ad39967802
createdAt: '2024-10-14T19:00:53.664Z'
updatedAt: '2024-10-14T19:00:53.664Z'
deletedAt: null
With Webhook Completed:
value:
id: b83b1558-de5b-4e45-b517-7bececbdd154
status: succeeded
inputContent:
files: []
messages: []
variables:
document:
file_url: https://example.com/document.pdf
outputContent:
role: assistant
structured_content: false
content:
fileSummary: >-
This document contains quarterly financial reports
showing a 15% revenue increase compared to last
quarter, with key highlights in operational efficiency
improvements and market expansion in the APAC region.
input_messages: >-
user: Please analyze this document and provide a
summary.
rawInput:
canvas_id: 95cec438-6080-44fe-8275-28b16bd40178
variables:
document:
file_url: https://example.com/document.pdf
webhook_url: https://your-webhook-url.com
rawOutput:
fileSummary: >-
This document contains quarterly financial reports
showing a 15% revenue increase compared to last quarter,
with key highlights in operational efficiency
improvements and market expansion in the APAC region.
compatibilityDate: '2024-10-14T00:00:00.000Z'
promptVersionId: 76065caa-c519-441a-8fe2-cc43e29664ab
promptApplicationId: null
workspaceId: 3f55cfd9-4427-4887-a181-d9ad39967802
createdAt: '2024-10-14T19:00:53.664Z'
updatedAt: '2024-10-14T19:01:15.892Z'
deletedAt: null
'400':
description: unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
x-codeSamples:
- lang: typescript
source: >
import { createTelaClient } from '@meistrari/tela-sdk-js'
const tela = createTelaClient({
apiKey: process.env.TELA_API_KEY,
})
const completion = await tela.completions.create<{ yourvariable:
string }>({
canvasId: process.env.TELA_CANVAS_ID,
variables: {
yourvariable: 'your value',
},
})
- lang: python
source: |
import os
from tela import create_tela_client
TELA_CANVAS_ID = os.getenv("TELA_CANVAS_ID")
TELA_API_KEY = os.getenv("TELA_API_KEY")
client = create_tela_client(
api_key=TELA_API_KEY,
)
webhook = client.completions.create(
canvas_id=TELA_CANVAS_ID,
variables={
"yourvariable": "your value",
},
)
- lang: javascript
source: |
import { createTelaClient } from '@meistrari/tela-sdk-js'
const tela = createTelaClient({
apiKey: process.env.TELA_API_KEY,
})
const completion = await tela.completions.create({
canvasId: process.env.TELA_CANVAS_ID,
variables: {
yourvariable: 'your value',
},
})
components:
schemas:
ChatCompletionRequest:
type: object
oneOf:
- $ref: '#/components/schemas/PromotedVersion'
- $ref: '#/components/schemas/SpecificVersion'
- $ref: '#/components/schemas/Workstation'
ChatCompletionResponses:
type: object
oneOf:
- $ref: '#/components/schemas/ChatCompletionResponse'
- $ref: '#/components/schemas/ChatCompletionWebhookResponse'
- $ref: '#/components/schemas/ChatCompletionStreamResponse'
Error: {}
PromotedVersion:
type: object
title: Promoted version
required:
- canvas_id
properties:
canvas_id:
type: string
description: The ID of the canvas to execute
variables:
$ref: '#/components/schemas/Variables'
messages:
$ref: '#/components/schemas/Messages'
webhook_url:
type: string
description: The URL to send webhooks to
stream:
type: boolean
description: Whether to stream the response
async:
type: boolean
description: Whether to make the execution async
override:
$ref: '#/components/schemas/Override'
SpecificVersion:
type: object
title: Specific version
required:
- version_id
properties:
version_id:
type: string
description: The ID of the version to execute
variables:
$ref: '#/components/schemas/Variables'
messages:
$ref: '#/components/schemas/Messages'
webhook_url:
type: string
description: The URL to send webhooks to
stream:
type: boolean
description: Whether to stream the response
async:
type: boolean
description: Whether to make the execution async
override:
$ref: '#/components/schemas/Override'
Workstation:
type: object
title: Workstation
required:
- application_id
properties:
application_id:
type: string
description: The ID of the application to execute
variables:
$ref: '#/components/schemas/Variables'
messages:
$ref: '#/components/schemas/Messages'
webhook_url:
type: string
description: The URL to send webhooks to
override:
$ref: '#/components/schemas/Override'
ChatCompletionResponse:
type: object
title: Chat completion response
properties:
id:
type: string
description: A unique identifier for this completion
object:
type: string
description: The object type, which is always "chat.completion"
created:
type: integer
description: The Unix timestamp (in seconds) of when the completion was created
choices:
type: array
description: An array of completion choices generated by the model
items:
type: object
properties:
message:
type: object
description: The message object containing the completion
properties:
role:
type: string
description: The role of the message author (e.g., "assistant")
content:
oneOf:
- type: object
- type: string
description: >-
The content of the message, which can be either a string
or an object
tool_calls:
type: array
description: An array of tool calls, if any
items:
type: object
description: A tool call object
ChatCompletionWebhookResponse:
type: object
title: Chat completion webhook response
description: >-
Response structure for a chat completion webhook. This represents the
data sent to the webhook URL when a chat completion is finished.
properties:
id:
type: string
description: Unique identifier for this chat completion response
status:
type: string
enum:
- created
- failed
- running
- succeeded
description: >-
The current status of the chat completion. 'created' means the
request has been received but processing hasn't started. 'running'
means the chat completion is currently being processed. 'succeeded'
means the chat completion has finished successfully. 'failed' means
the chat completion encountered an error and couldn't complete.
input_content:
type: object
description: >-
Contains information about the input provided for this chat
completion
properties:
variables:
$ref: '#/components/schemas/Variables'
description: Variables passed to the chat completion, including any file URLs
messages:
type: array
description: Array of messages that were part of the input
items:
type: object
properties:
role:
type: string
description: >-
The role of the message sender (e.g., 'user', 'assistant',
'system')
content:
oneOf:
- type: string
- type: object
properties:
type:
type: string
enum:
- text
- image_url
text:
type: string
image_url:
type: object
properties:
url:
type: string
detail:
type: string
enum:
- auto
- high
- low
description: >-
The content of the message. Can be a string for text
messages, or an object for more complex content types like
images.
function_call:
type: object
description: >-
Optional. Information about a function call, if
applicable.
properties:
name:
type: string
arguments:
type: string
files:
type: array
description: Information about files used in the chat completion
items:
type: object
properties:
name:
type: string
used_at:
type: string
enum:
- variables
- messages
parsed_content:
type: string
url:
type: string
type:
type: string
enum:
- image
- file
output_content:
type: object
description: Contains the output generated by the chat completion
properties:
role:
type: string
enum:
- system
- user
- assistant
- function
description: The role of the entity providing the output
tool_calls:
type: array
description: >-
Optional. Information about tool calls made during the
completion.
items:
type: object
properties:
name:
type: string
arguments:
type: string
information:
type: object
description: Optional. Additional information about the completion process.
properties:
duration:
type: number
cost:
type: number
input_tokens:
type: integer
output_tokens:
type: integer
has_structured_output:
type: boolean
description: Indicates whether the output has a structured format
content:
type: object
description: The main content of the chat completion output
input_messages:
type: string
description: Optional. The input messages in a string format.
raw_input:
type: object
nullable: true
description: The original input parameters provided for this chat completion
properties:
version_id:
type: string
description: The ID of the version used for this chat completion
canvas_id:
type: string
description: The ID of the canvas used for this chat completion
application_id:
type: string
description: The ID of the application associated with this chat completion
webhook_url:
type: string
description: The URL where webhook notifications are sent
variables:
$ref: '#/components/schemas/Variables'
messages:
$ref: '#/components/schemas/Messages'
override:
$ref: '#/components/schemas/Override'
raw_output:
type: object
additionalProperties: true
description: The raw output from the chat completion process
compatibility_date:
type: string
format: date-time
description: The date used for compatibility checks
prompt_version_id:
type: string
description: The ID of the prompt version used for this chat completion
prompt_application_id:
type: string
nullable: true
description: The ID of the prompt application, if applicable
workspace_id:
type: string
description: The ID of the workspace where this chat completion was executed
created_at:
type: string
format: date-time
description: The timestamp when this chat completion was created
updated_at:
type: string
format: date-time
description: The timestamp when this chat completion was last updated
ChatCompletionStreamResponse:
type: object
title: Chat completion stream response
properties:
id:
type: string
description: The ID of the completion
object:
type: string
description: The object of the completion
created:
type: integer
description: The created time of the completion
model:
type: string
description: The model of the completion
choices:
type: array
items:
type: object
properties:
delta:
type: object
properties:
role:
type: string
nullable: true
content:
type: string
nullable: true
function_call:
type: object
nullable: true
properties:
name:
type: string
nullable: true
arguments:
type: string
nullable: true
finish_reason:
type: string
nullable: true
index:
type: integer
logprobs:
type: number
nullable: true
message:
type: object
description: The complete message object for the stream response
properties:
role:
type: string
description: The role of the message author (e.g., "assistant")
content:
type: string
nullable: true
description: The content of the message
function_call:
type: object
nullable: true
description: Information about a function call, if applicable
properties:
name:
type: string
nullable: true
description: The name of the function being called
arguments:
type: string
nullable: true
description: The arguments passed to the function
tool_calls:
type: array
description: An array of tool calls made during the completion
items:
type: object
properties:
name:
type: string
description: The name of the tool being called
arguments:
type: string
description: The arguments passed to the tool
structured_content:
type: object
additionalProperties: true
description: Structured content of the message, if applicable
Variables:
type: object
description: The variables to pass to the canvas
additionalProperties:
oneOf:
- type: string
- type: object
properties:
file_url:
type: string
options:
type: object
required:
- file_url
Messages:
type: array
items:
type: object
properties:
role:
type: string
enum:
- user
- assistant
content:
oneOf:
- type: string
description: The content of the message as a string
- $ref: '#/components/schemas/FileMessage'
description: The content of the message, either as a string or a file
required:
- role
- content
Override:
type: object
description: >-
Override default settings specified in the canvas. This allows for
fine-tuning the completion behavior for this specific request.
properties:
model:
type: string
description: >-
The specific model to use for this completion. If not specified, the
default model set in the canvas will be used.
temperature:
type: number
description: >-
Controls randomness in the output. Values between 0 and 1. Lower
values make the output more focused and deterministic.
type:
type: string
enum:
- chat
- completion
description: Specifies whether to use a chat or completion model.
functions:
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
description:
type: string
parameters:
type: object
properties:
type:
type: string
enum:
- object
properties:
type: object
additionalProperties: true
required:
type: array
items:
type: string
description: >-
An array of functions that the model can call. This allows for more
structured and interactive completions.
structured_output:
type: object
properties:
enabled:
type: boolean
description: Whether to enable structured output for this completion.
schema:
type: object
properties:
properties:
type: object
additionalProperties: true
description: Defines the properties of the structured output
type:
type: string
enum:
- object
description: >-
The type of the schema, always "object" for structured
output
title:
type: string
description: The title of the schema
description:
type: string
description: A description of the schema
required:
type: array
items:
type: string
description: An array of required property names
description: >-
The schema defining the structure of the output. This is used
when structured output is enabled.
description: Configuration for generating structured output.
required:
- type
FileMessage:
type: object
properties:
file_url:
type: string
description: The URL of the file
````