The input schema type (Zod schema or plain object type)
The output schema type (Zod schema or plain object type)
Gets the unique identifier of this canvas.
The canvas ID.
Gets whether this canvas is a workflow.
True if the canvas is a workflow.
Gets whether this canvas is a workstation. This is true if an application ID is provided.
True if the canvas is a workstation.
Gets the name of this canvas, if provided.
The canvas name or undefined.
Gets the version identifier of this canvas, if specified. When undefined, the latest promoted version is used.
The version ID or undefined.
Prepares to execute this canvas in batch.
The parameters for the batch.
Configuration options for batch execution.
Batch executions are always asynchronous and return results via output file. Unlike single executions, batches do not support streaming or synchronous modes.
Optionallabel?: stringOptional label for this execution when using applicationId. This label can be used to identify or categorize the execution. Note: This field is only applicable when applicationId is provided.
Optionalmessages?: { content: string; role: string }[]An array of previous messages in the conversation. Each message should have a 'role' (e.g., 'user', 'assistant') and 'content'.
Optionaloverride?: {Override default settings specified in the canvas. This allows for fine-tuning the completion behavior for this specific request.
Optionalfunctions?: {An array of functions that the model can call. This allows for more structured and interactive completions.
Optionalmodel?: stringThe specific model to use for this completion. If not specified, the default model set in the canvas will be used.
Optionaltemperature?: numberControls randomness in the output. Values between 0 and 1. Lower values make the output more focused and deterministic.
Specifies whether to use a chat or completion model.
OptionalpollingInterval?: string | numberTime (in milliseconds if number) between polling attempts (e.g. "1s", "1m", "1h", "1d"). Controls how frequently the SDK checks batch completion status.
OptionalpollingTimeout?: string | numberMaximum time (in milliseconds if number) to wait for completion before timing out (e.g. "1s", "1m", "1h", "1d"). After timeout, polling stops but the batch continues processing on the server.
Optionaltags?: string[]Optional array of tags to associate with this execution. Tags can be used for filtering, categorization, and analytics.
Optionalwebhook?: BatchWebhookConfigWebhook configuration for batch completion notifications. Supports both URL and custom headers to forward.
OptionalwebhookUrl?: stringOptional webhook URL to receive completion notifications. The server will POST to this URL when the batch completes, fails, or is canceled.
The batch instance that can be used to manage the batch.
const batch = canvas.createBatch({
pollingInterval: '1s',
pollingTimeout: '1m',
webhookUrl: 'https://example.com/webhook',
})
batch.add({
referenceId: crypto.randomUUID(), // Optional
variables: { query: 'Hello' },
})
const execution = await batch.execute()
const result = await execution.result
const resultFile = await execution.downloadOutputFile()
Executes this canvas with the provided input variables. Creates and starts a canvas execution, handling variable validation and schema parsing.
Returns a promise-like object that allows flexible usage patterns:
const exec = await canvas.execute(vars)const result = await canvas.execute(vars).resultfor await (const chunk of canvas.execute(vars, { stream: true }).result)Input variables to pass to the canvas template.
Optionalparams: SyncExecutionParamsOptional execution parameters (sync/async/stream configuration).
A promise-like object with a result property for direct result access.
// Direct result access (recommended for simple cases)
const result = await canvas.execute({ query: "Hello" }).result;
// Get execution object for control (e.g., to abort)
const execution = await canvas.execute({ query: "Hello" });
const result = await execution.result;
// Asynchronous execution with polling
const result = await canvas.execute(
{ query: "Hello" },
{ async: true, pollingInterval: 500 }
).result;
// Streaming execution
for await (const chunk of canvas.execute(
{ query: "Hello" },
{ stream: true }
).result) {
console.log(chunk);
}
// Execution with tags
const result = await canvas.execute(
{ query: "Hello" },
{ tags: ["production", "analytics"] }
).result;
Executes this canvas with the provided input variables. Creates and starts a canvas execution, handling variable validation and schema parsing.
Returns a promise-like object that allows flexible usage patterns:
const exec = await canvas.execute(vars)const result = await canvas.execute(vars).resultfor await (const chunk of canvas.execute(vars, { stream: true }).result)Input variables to pass to the canvas template.
Optionalparams: AsyncExecutionParamsOptional execution parameters (sync/async/stream configuration).
A promise-like object with a result property for direct result access.
// Direct result access (recommended for simple cases)
const result = await canvas.execute({ query: "Hello" }).result;
// Get execution object for control (e.g., to abort)
const execution = await canvas.execute({ query: "Hello" });
const result = await execution.result;
// Asynchronous execution with polling
const result = await canvas.execute(
{ query: "Hello" },
{ async: true, pollingInterval: 500 }
).result;
// Streaming execution
for await (const chunk of canvas.execute(
{ query: "Hello" },
{ stream: true }
).result) {
console.log(chunk);
}
// Execution with tags
const result = await canvas.execute(
{ query: "Hello" },
{ tags: ["production", "analytics"] }
).result;
Executes this canvas with the provided input variables. Creates and starts a canvas execution, handling variable validation and schema parsing.
Returns a promise-like object that allows flexible usage patterns:
const exec = await canvas.execute(vars)const result = await canvas.execute(vars).resultfor await (const chunk of canvas.execute(vars, { stream: true }).result)Input variables to pass to the canvas template.
Optionalparams: StreamExecutionParamsOptional execution parameters (sync/async/stream configuration).
A promise-like object with a result property for direct result access.
// Direct result access (recommended for simple cases)
const result = await canvas.execute({ query: "Hello" }).result;
// Get execution object for control (e.g., to abort)
const execution = await canvas.execute({ query: "Hello" });
const result = await execution.result;
// Asynchronous execution with polling
const result = await canvas.execute(
{ query: "Hello" },
{ async: true, pollingInterval: 500 }
).result;
// Streaming execution
for await (const chunk of canvas.execute(
{ query: "Hello" },
{ stream: true }
).result) {
console.log(chunk);
}
// Execution with tags
const result = await canvas.execute(
{ query: "Hello" },
{ tags: ["production", "analytics"] }
).result;
Fetches an existing async execution by its ID.
This method retrieves the current state of an async execution that was previously started on this canvas. Only async executions can be fetched, as they are the only ones with persistent UUIDs on the server.
The UUID of the async execution to fetch.
Optionaloptions: { pollingInterval?: string | number; pollingTimeout?: string | number }Optional configuration for polling behavior.
OptionalpollingInterval?: string | numberTime in milliseconds between polling attempts (default: 1000).
OptionalpollingTimeout?: string | numberMaximum time in milliseconds to wait for completion (default: 60000).
A promise resolving to a CanvasExecution instance with the fetched state.
// Start an async execution
const execution = await canvas.execute({ query: 'test' }, { async: true })
const executionId = execution.id
// Later, fetch the execution by ID
const fetched = await canvas.getExecution(executionId)
console.log(fetched.status) // 'running', 'succeeded', or 'failed'
// Use poll() for event-driven progress tracking
fetched.on('statusChange', (status) => console.log('Status:', status))
fetched.poll()
StaticgetGets a canvas by its ID.
The options to use to get the canvas.
The ID of the canvas to get.
The version ID of the canvas to get.
The application ID of the canvas to get.
The client to use to make the request.
The input schema of the canvas to get.
The output schema of the canvas to get.
OptionalskipSchemaValidation?: booleanWhether to skip schema validation warnings during canvas retrieval. When true, no warnings will be logged for schema mismatches.
The client to use to make the request.
The canvas.
Represents a canvas (prompt template) from the Tela API.
Canvas instances are retrieved using
tela.canvas.get()and provide methods for executing prompts with various modes (sync, async, streaming).