Trigger API

Overview

Triggers store the first-message content and optional variables for a deployment. Create is authenticated. Get by id is public so chat UIs can load a trigger from a tid URL param.

Base path: /v1/runner/{deployment_id}

Create trigger

Creates a trigger for a published deployment.

POST /v1/runner/{deployment_id}/trigger

Auth: x-api-key (or dashboard session Bearer token).

Body

Field	Type	Description
`content`	`MessageContent[]`	First-message content (same shape as runner)
`variables`	object	Optional arbitrary variables
`ui_surface`	string	Optional surface hint (`chat`, `assessment`, …)
`ttl_hours`	integer \| null	Hours until expiry. Default `24`. Pass `null` for no expiry

Response

Field	Type	Description
`id`	string	8-character public trigger id (`tid` in chat URLs)
`deployment_id`	UUID	Deployment
`workflow_id`	integer	Parent workflow
`ui_surface`	string \| null	Surface hint
`content`	array	Stored content
`variables`	object \| null	Stored variables
`conversation_id`	UUID \| null	Set after first successful use
`workflow_log_id`	integer \| null	Linked log when available
`created_at`	datetime	Created time
`expires_at`	datetime \| null	Expiry time
`expired`	boolean	Computed: `expires_at` is in the past

import { amarsia } from "@amarsia/sdk";

const client = amarsia.init({
  apiKey: process.env.AMARSIA_API_KEY!,
  deploymentId: "YOUR_DEPLOYMENT_ID",
});

const trigger = await client.trigger.create({
  content: [{ type: "text", text: "Let us begin. Student: Riya." }],
  variables: { studentName: "Riya" },
  uiSurface: "chat",
  ttlHours: 24,
});

const url = `https://chat.amarsia.com/chat/${trigger.deployment_id}?tid=${trigger.id}`;

Get trigger

Public read. Safe to call repeatedly. Does not mutate the trigger.

GET /v1/runner/{deployment_id}/trigger/{trigger_id}

Auth: none.

Use conversation_id and expired to decide UI state:

Condition	UI / client action
`expired`	Show expired; do not start or continue
`conversation_id` null	Fire: start conversation with stored content + `trigger_id`
`conversation_id` set	Resume that conversation

const trigger = await client.trigger.get({ triggerId: "TRIGGER_UUID" });

List triggers

Paginated history for the dashboard (authenticated).

GET /v1/runner/{deployment_id}/triggers?page=1&page_size=20

Runner integration

Pass optional trigger_id on v1/v2 one-shot and conversation requests. For conversations, only on the first message (no conversation_id yet).

If the workflow has trigger_required: true and the request omits trigger_id, the runner returns 400.

Workflow setting endpoint (dashboard):

POST /v1/workflow/{workflow_id}/trigger-settings

Body: { "trigger_required": true }

Public widget-meta includes trigger_required so chat UIs can block early.