Batch Generate

The Batch Generate endpoint lets you fetch content for up to 20 templates in a single request. This is useful for multi-template journeys where you need content for several touchpoints at once — for example, fetching a welcome email, a follow-up, and a re-engagement message in one call.

Endpoint

POST https://worker.justwords.ai/api/batch-generate/:org_slug

Authentication

This endpoint requires authentication via an API key. Include your key in the X-Api-Key header or as a Bearer token in the Authorization header.

See the Quickstart for details on creating and managing API keys.

Request

Path Parameters

Parameter	Type	Required	Description
`org_slug`	string	Yes	Your organization identifier (e.g., `your-company-name`).

Request Body

Field	Type	Required	Default	Description
`requests`	array	Yes	-	Array of generation requests (min 1, max 20). See below for object shape.
`attrs`	object	No	`{}`	Key-value pairs for targeting/filtering, shared across all requests.
`fields`	object	No	`{}`	Key-value pairs for LiquidJS template variable substitution, shared across all requests.
`user_id`	string	No	-	Unique identifier for the end user, shared across all requests.
`lookback_days`	number	No	`14`	Number of days of historical data to use for optimization.
`offset_days`	number	No	`3`	Number of days to offset the lookback window.
`use_cache`	boolean	No	`true`	Whether to use cached results.
`epsilon`	number	No	-	Exploration rate override for the bandit algorithm.
`trace`	boolean	No	`false`	Include debug trace information in the response.

Request Object Shape

Each object in the requests array has the following fields:

Field	Type	Required	Description
`template_id`	string	Yes	Unique identifier for the template.
`copy_id`	string	No	Force a specific variant by ID.
`bucket_name`	string	No	Target a specific bucket/segment.
`tracking_id`	string	No	Unique identifier for tracking this message through downstream events.

Examples

Basic Request

Fetch content for a welcome journey with three touchpoints:

curl -X POST https://worker.justwords.ai/api/batch-generate/your-org \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      { "template_id": "welcome-email" },
      { "template_id": "follow-up-day3" },
      { "template_id": "re-engagement-day7" }
    ],
    "user_id": "user_123"
  }'

const response = await fetch(
  'https://worker.justwords.ai/api/batch-generate/your-org',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'your_api_key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      requests: [
        { template_id: 'welcome-email' },
        { template_id: 'follow-up-day3' },
        { template_id: 're-engagement-day7' },
      ],
      user_id: 'user_123',
    }),
  }
);

const data = await response.json();
console.log(data);

import requests

url = "https://worker.justwords.ai/api/batch-generate/your-org"
headers = {
    "X-Api-Key": "your_api_key",
    "Content-Type": "application/json"
}
payload = {
    "requests": [
        {"template_id": "welcome-email"},
        {"template_id": "follow-up-day3"},
        {"template_id": "re-engagement-day7"}
    ],
    "user_id": "user_123"
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()
print(data)

With Shared Fields and Per-Request Tracking

{
  "requests": [
    { "template_id": "welcome-email", "tracking_id": "msg_001" },
    { "template_id": "follow-up-day3", "tracking_id": "msg_002" },
    { "template_id": "re-engagement-day7", "tracking_id": "msg_003" }
  ],
  "user_id": "user_123",
  "fields": {
    "user_name": "Alice",
    "account_type": "premium"
  },
  "attrs": {
    "plan": "premium",
    "region": "us-east"
  }
}

Shared fields, attrs, and user_id apply to every request in the batch. Each request can have its own tracking_id.

Response

Success Response (200 OK)

The response is a JSON object keyed by template_id, where each value is a standard generation response:

{
  "welcome-email": {
    "tracking_id": "msg_001",
    "copy": {
      "id": "variant_abc123",
      "vars": {
        "subject": "Welcome to our platform, Alice!",
        "body": "We're excited to have you join us."
      }
    }
  },
  "follow-up-day3": {
    "tracking_id": "msg_002",
    "copy": {
      "id": "variant_def456",
      "vars": {
        "subject": "How's it going, Alice?",
        "body": "Here are some tips to get the most out of your account."
      }
    }
  },
  "re-engagement-day7": {
    "tracking_id": "msg_003",
    "copy": {
      "id": "variant_ghi789",
      "vars": {
        "subject": "We miss you!",
        "body": "Come back and see what's new."
      }
    }
  }
}

Each entry follows the same format as the Generate endpoint response.