Run Canvas

TypeScript

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

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

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

curl --request POST \
  --url https://api.tela.com/v2/chat/completions \
  --header 'Content-Type: application/json' \
  --data '
{
  "canvas_id": "<string>",
  "variables": {},
  "messages": [
    {
      "content": "<string>"
    }
  ],
  "webhook_url": "<string>",
  "stream": true,
  "async": true
}
'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tela.com/v2/chat/completions",
  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([
    'canvas_id' => '<string>',
    'variables' => [
        
    ],
    'messages' => [
        [
                'content' => '<string>'
        ]
    ],
    'webhook_url' => '<string>',
    'stream' => true,
    'async' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$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/v2/chat/completions"

	payload := strings.NewReader("{\n  \"canvas_id\": \"<string>\",\n  \"variables\": {},\n  \"messages\": [\n    {\n      \"content\": \"<string>\"\n    }\n  ],\n  \"webhook_url\": \"<string>\",\n  \"stream\": true,\n  \"async\": true\n}")

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

	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/v2/chat/completions")
  .header("Content-Type", "application/json")
  .body("{\n  \"canvas_id\": \"<string>\",\n  \"variables\": {},\n  \"messages\": [\n    {\n      \"content\": \"<string>\"\n    }\n  ],\n  \"webhook_url\": \"<string>\",\n  \"stream\": true,\n  \"async\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.tela.com/v2/chat/completions")

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

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"canvas_id\": \"<string>\",\n  \"variables\": {},\n  \"messages\": [\n    {\n      \"content\": \"<string>\"\n    }\n  ],\n  \"webhook_url\": \"<string>\",\n  \"stream\": true,\n  \"async\": true\n}"

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

{
  "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."
        }
      }
    }
  ]
}

POST

chat

completions

TypeScript

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

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

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

curl --request POST \
  --url https://api.tela.com/v2/chat/completions \
  --header 'Content-Type: application/json' \
  --data '
{
  "canvas_id": "<string>",
  "variables": {},
  "messages": [
    {
      "content": "<string>"
    }
  ],
  "webhook_url": "<string>",
  "stream": true,
  "async": true
}
'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tela.com/v2/chat/completions",
  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([
    'canvas_id' => '<string>',
    'variables' => [
        
    ],
    'messages' => [
        [
                'content' => '<string>'
        ]
    ],
    'webhook_url' => '<string>',
    'stream' => true,
    'async' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$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/v2/chat/completions"

	payload := strings.NewReader("{\n  \"canvas_id\": \"<string>\",\n  \"variables\": {},\n  \"messages\": [\n    {\n      \"content\": \"<string>\"\n    }\n  ],\n  \"webhook_url\": \"<string>\",\n  \"stream\": true,\n  \"async\": true\n}")

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

	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/v2/chat/completions")
  .header("Content-Type", "application/json")
  .body("{\n  \"canvas_id\": \"<string>\",\n  \"variables\": {},\n  \"messages\": [\n    {\n      \"content\": \"<string>\"\n    }\n  ],\n  \"webhook_url\": \"<string>\",\n  \"stream\": true,\n  \"async\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.tela.com/v2/chat/completions")

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

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"canvas_id\": \"<string>\",\n  \"variables\": {},\n  \"messages\": [\n    {\n      \"content\": \"<string>\"\n    }\n  ],\n  \"webhook_url\": \"<string>\",\n  \"stream\": true,\n  \"async\": true\n}"

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

{
  "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."
        }
      }
    }
  ]
}

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:

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

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

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:

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

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

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

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

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

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.

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

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

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.

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

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

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 section in the completion API guide.

Body

application/json

The canvas to execute

Promoted version
Specific version
Workstation

canvas_id

string

required

The ID of the canvas to execute

variables

object

The variables to pass to the canvas

Show child attributes

messages

object[]

Show child attributes

webhook_url

string

The URL to send webhooks to

stream

boolean

Whether to stream the response

async

boolean

Whether to make the execution async

override

object

Override default settings specified in the canvas. This allows for fine-tuning the completion behavior for this specific request.

Show child attributes

Response

Successful completions

Chat completion response
Chat completion webhook response
Chat completion stream response

string

A unique identifier for this completion

object

string

The object type, which is always "chat.completion"

created

integer

The Unix timestamp (in seconds) of when the completion was created

choices

object[]

An array of completion choices generated by the model

Show child attributes

Retrieve Canvas Run

Completion

File

Test Case

Prompt Version

Task

Files

Single File Processing

Using Vault URLs

Multiple Files in a Single Variable

Streaming

Webhook

Body

Response

​Files

​Single File Processing

​Using Vault URLs

​Multiple Files in a Single Variable

​Streaming

​Webhook

Body

Response

Files

Single File Processing

Using Vault URLs

Multiple Files in a Single Variable

Streaming

Webhook