Skip to main content
POST
/
api
/
campaigns
/
ai-chat-sessions
/
{id}
/
generate-examples
Generate example emails for a campaign AI chat session
curl --request POST \
  --url https://app.puffle.ai/api/campaigns/ai-chat-sessions/{id}/generate-examples \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "leads": [
    {
      "first_name": "<string>",
      "last_name": "<string>",
      "full_name": "<string>",
      "company": "<string>",
      "position": "<string>",
      "headline": "<string>",
      "linkedin_url": "<string>",
      "custom_fields": {}
    }
  ],
  "sequenceContext": {
    "position": 4503599627370495,
    "total_nodes": 4503599627370495,
    "prior_nodes": [
      {}
    ]
  },
  "isFirstBatch": true
}
'
{ "runId": "run_def456", "publicAccessToken": "tr_pat_def456..." }

​
Overview

Dispatches the generate-email-examples Trigger.dev task, which reads the session’s current skeleton and produces one AI-written sample email per lead in the request body. Results are written back onto the session as generated_examples. The call is async via Trigger.dev: the HTTP response returns a runId (and a publicAccessToken for the Trigger.dev realtime SDK) as soon as the task is enqueued. Observe progress by subscribing to the run via the realtime SDK, or by polling GET /api/campaigns/ai-chat-sessions/{id} until task_status returns to null and generated_examples is populated.

​
Prerequisites

The session must already have a non-null skeleton. Build one first by calling runAiChatTurn a few times until the framework LLM converges. Calling this endpoint before a skeleton exists returns 400 (Session has no framework yet. Chat first to create one.).

​
Concurrency

The server atomically sets task_status: "generating_examples" before dispatching. If another generate-examples run (or a /turn call) is already in flight, the update finds task_status !== null, fails to claim, and the handler returns 409. Wait for task_status to clear, then retry.

​
AI agent notes

Lead count drives cost and duration. Each lead is a separate LLM call. Budget roughly 1–2 cents per lead and 2–4 s of wall-clock time per lead. Keep leads small (3–10) unless you actually need every prospect’s sample.isFirstBatch controls append vs seed. Pass true on the first call for a session to overwrite generated_examples. Subsequent calls with false append — useful for top-up runs that regenerate samples for just the newly-added prospects.Rate limit: one active task per session. A 409 means either a /turn run or a prior /generate-examples run is still going. Poll GET .../{id} every 2–5 s until task_status === null.On 500 during dispatch. The server releases the claim before returning 500 — the session is immediately retryable. No manual task_status reset is needed.When 400 says no framework. Build one via POST .../turn. A typical warmup is 2–4 turns. The skeleton field on the session must be non-null before this endpoint will accept a call.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
id
string<uuid>
required

AI chat session UUID

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Body

application/json

leads is the only required field. The generator reads the session's current skeleton and produces one example email per lead.

​
leads
object[]
required

Leads to generate sample emails for. Must contain at least one lead.

Minimum array length: 1
​
sequenceContext
object

Context about where this email sits in the campaign sequence — helps the LLM write follow-ups that acknowledge prior touches.

​
isFirstBatch
boolean

Signals whether this is the first batch of examples for the session. The generator may seed generated_examples on true and append on false.

Response

Task dispatched. Poll the session or subscribe to the Trigger.dev run for results.

​
runId
string
required

Trigger.dev run id. Use with the Trigger.dev realtime SDK (plus publicAccessToken) for progress events, or poll GET /api/campaigns/ai-chat-sessions/{id} until task_status returns to null and generated_examples is populated.

​
publicAccessToken
string
required

Short-lived Trigger.dev public access token scoped to this run.