Skip to main content
POST
Record Canvas Interaction
For AI agents, use https://docs.tavus.io/openapi.yaml for the full HTTP API contract.
See Canvas interactions for per-component value rules, webhook delivery, and the full error catalog.

Path Parameters

conversation_id
string
required

The unique identifier of the conversation.

Example:

"c123456"

Body

application/json

Body for Record Canvas Interaction. value validation depends on component and type - see Canvas interactions.

interaction_id
string
required

Idempotency key. Unique per logical interaction; reuse verbatim on retries. Tavus clients use ci_{tool_call_id}_{type}_{uuid}.

Required string length: 1 - 128
Example:

"ci_call_8f2d41_submit_5e0b7c2a"

tool_call_id
string
required

The id of the Canvas invocation that showed the card. Ties the interaction to a specific card instance.

Required string length: 1 - 128
Example:

"call_8f2d41"

component
enum<string>
required

Component id.

Available options:
canvas.question,
canvas.input,
canvas.calendar,
canvas.scheduling_embed,
canvas.text,
canvas.image,
canvas.video,
canvas.chart,
canvas.alert
Example:

"canvas.question"

component_version
string
required

Component contract version. v1 for all current components.

Example:

"v1"

type
enum<string>
required

Interaction type. Submit-capable components also allow submit and skip.

Available options:
submit,
skip,
dismiss,
clear,
error,
heartbeat
Example:

"submit"

value
object
required

Interaction payload. At most 16 KB serialized. Shape depends on component and type.

Example:
metadata
object

Optional client annotations, at most 4 KB serialized. Not part of idempotency matching.

Example:

Response

Interaction recorded (or idempotent replay)

success
boolean
Example:

true