REST API

API reference

Start runs, inspect evidence, send events, and receive signed results.

New to Tremi? Follow the first-run guide to publish a sample workflow, simulate it, and inspect the result.

Base URLhttps://www.tremi.ai/api/v1

1
Publish a workflow
Publish a draft in Tremi to give it a stable workflow slug.
Open workflows
2
Create an API key
Create a key in Settings → API keys and copy it once.
Open API keys
3
Start a run
Send the recipient and any variables used by your published workflow.
Read the request contract

POST/workflows/{workflow_slug}/runs

Authentication

Tremi authenticates API requests with workspace API keys. Send the key as a Bearer token on every request.

Authorization header

Authorization: Bearer $TREMI_API_KEY

Keep API keys server-side.Keys begin with trm_live_, are shown once, and should never be committed to source control.

Scopes

Scope	Allows
`workflows:run`	Create runs from published workflows.
`workflows:read`	Read published workflow contracts through Tremi MCP.
`workflows:simulate`	Create contained workflow simulations through Tremi MCP.
`runs:read`	Retrieve run state and evidence.
`runs:events`	Emit customer-defined events into a run.
`runs:cancel`	Cancel an active run.

For the Streamable HTTP endpoint and client configuration, see the Tremi MCP guide.

Idempotency

Every mutating endpoint requires an Idempotency-Key header so a network retry cannot create a second logical action.

Use one stable key for each logical create, event, or cancel request.
A replay with the same key and request returns the stored response and Idempotency-Replayed: true.
Reusing a key with a different request returns 409 idempotency_conflict.
Keys are required, non-empty, and at most 255 characters.

Send your own X-Request-Id when you need to correlate Tremi responses with application logs. Tremi returns it on the response or creates one for you.

POST/workflows/{workflow_slug}/runs

Create a run

Starts the latest published version of a workflow for one recipient.

Scope: workflows:run
Idempotency: Required
Success: 202 Accepted

A live workflow start uses 1 Tremi credit. Each outbound attempt uses 1 additional credit only after its provider accepts it. Simulations and idempotent replays use 0 credits.

REQUEST

Create a run

curl https://www.tremi.ai/api/v1/workflows/evaluation-follow-up/runs \
  -X POST \
  -H "Authorization: Bearer $TREMI_API_KEY" \
  -H "Idempotency-Key: order_4021" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": {
      "externalId": "contact_001",
      "phone": "+15551234567",
      "timezone": "America/New_York"
    },
    "variables": { "first_name": "User" },
    "mode": "live"
  }'

202 Accepted

{
  "id": "run_01K...",
  "state": "queued",
  "workflowVersion": 4,
  "createdAt": "2026-08-27T14:12:00.000Z"
}

Path parameters

Parameter	Type	Required	Description
`workflow_slug`	string	Yes	Stable slug of a published workflow.

Request body

Field	Type	Required	Description
`recipient`	object	Yes	Destinations and external identity for this run.
`recipient.externalId`	string	No	Customer-defined recipient identifier.
`recipient.phone`	string	By workflow	E.164 number required by voice or SMS steps.
`recipient.email`	string	By workflow	Email address required by email steps.
`recipient.timezone`	string	No	IANA time zone used for recipient-local timing.
`variables`	object	No	String, number, boolean, or null values referenced by workflow content.

GET/runs/{run_id}

Retrieve a run

Returns the current run state, outcome, attempt summary, and canonical event timeline.

Scope: runs:read
Idempotency: Not used
Success: 200 OK

Path parameters

Parameter	Type	Required	Description
`run_id`	string	Yes	Public run identifier returned by Create a run.

Response

Field	Type	Description
`id`	string	Public run identifier.
`state`	run state	Current lifecycle state.
`outcome`	run outcome \| null	Terminal result when one is known.
`workflowVersion`	number	Immutable workflow version captured at creation.
`mode`	live \| simulation	Dispatch mode selected at creation.
`attempts`	array	Channel, provider, state, and timing for each attempt.
`events`	array	Canonical run and provider events in occurrence order.
`createdAt`	date-time	ISO 8601 creation time.
`updatedAt`	date-time

POST/runs/{run_id}/events

Emit an event

Adds a customer-defined event to a run and evaluates custom stop conditions.

Scope: runs:events
Idempotency: Required
Success: 200 OK

Request body

Field	Type	Required	Description
`type`	string	Yes	Lowercase event name such as meeting.scheduled.
`data`	object	No	Customer-defined event payload. Defaults to an empty object.

If the event matches a published custom stop condition, Tremi completes the run with the goal_achieved outcome and dismisses remaining work.

Request body

{
  "type": "meeting.scheduled",
  "data": {
    "meetingId": "meeting_2048"

POST/runs/{run_id}/cancel

Cancel a run

Cancels an active run and prevents remaining attempts from dispatching.

Scope: runs:cancel
Idempotency: Required
Success: 200 OK

This endpoint has no request body. Canceling an already terminal run is safe and returns its current state and outcome.

200 response

{
  "id": "run_01K...",
  "state": "canceled",
  "outcome": "manual_cancellation"
}

Result webhooks

Result webhooks deliver provider-neutral run events to an HTTPS endpoint configured in workspace settings.

Add a result webhook in Settings → Webhooks. Endpoints must use public HTTPS without embedded credentials or a custom port.

Request headers

Header	Value
`Content-Type`	application/json
`User-Agent`	Tremi-Result-Webhook/1.0
`Tremi-Event-Id`	Unique event identifier.
`Tremi-Timestamp`	Unix timestamp used to sign the body.
`Tremi-Signature`	v1= followed by the HMAC-SHA256 signature.

Result envelope

{
  "id": "evt_01K...",
  "type": "run.completed",
  "createdAt": "2026-08-27T14:13:26.000Z"

Verify signatures

Verify the signature against the unmodified request body before parsing JSON or changing application state.

Read Tremi-Timestamp, Tremi-Signature, and the raw UTF-8 body.
Compute HMAC-SHA256 over ${timestamp}.${rawBody} with the endpoint signing secret.
Compare the hexadecimal digest to the value after v1= using a constant-time comparison.
Reject stale timestamps and deduplicate deliveries by Tremi-Event-Id.

Node.js signature verification

import { createHmac, timingSafeEqual } from 'node:crypto'

const payload = `${timestamp}.${rawBody}`
const expected = createHmac('sha256', process.envTREMI_WEBHOOK_SECRET
  updatepayload
  digest
 supplied  signaturereplace^v1 

 valid  expectedlength  suppliedlength  timingSafeEqual
  Bufferexpected
  Buffersupplied

Run states

A run moves through non-terminal states until it completes, fails, or is canceled.

State	Terminal	Meaning
`queued`	No	Accepted and waiting for execution.
`scheduled`	No	Waiting for a scheduled dispatch time.
`running`	No	An attempt is being dispatched or reconciled.
`waiting`	No	Waiting between workflow steps or for provider evidence.
`attention`	No	Execution stopped because provider acceptance is uncertain or needs review.
`completed`	Yes	A stop condition matched or the sequence ended successfully.
`failed`	Yes	Execution ended after a provider failure.
`canceled`	Yes	Canceled by the customer.

Terminal outcomes

Outcome	Meaning
`goal_achieved`	A configured goal or custom stop condition matched.
`sequence_exhausted`	Every applicable workflow step finished without another stop condition.
`recipient_opt_out`	The recipient opted out of communication.
`manual_cancellation`	The run was canceled through the API or console.
`provider_failure`	A provider failure ended the run.

Error codes

Errors use one JSON envelope. The response and X-Request-Id share the same request identifier.

Error response

{
  "error": {
    "code": "validation_failed",
    "message": "The request body is invalid.",
    "requestId": "req_01K...",
    "details": {}
  }
}

Code	Typical status	Meaning

Header	Description
`Location`	Points to `/api/v1/runs/{run_id}`.
`Idempotency-Replayed`	True when this response was replayed from the same request.
`X-Request-Id`	Request correlation identifier.

API reference

Publish a workflow

Create an API key

Start a run

Authentication

Scopes

Idempotency

Create a run

Path parameters

Request body

Path parameters

Response

Request body

Result webhooks

Request headers

Verify signatures

Run states

Terminal outcomes

Error codes

Response headers