Generate

The Generate endpoint is the core of the JustAI API. It selects and returns personalized content variants, learning which variants perform best for different user segments.

Endpoint

POST https://worker.justwords.ai/api/generate/:org_slug
GET https://worker.justwords.ai/api/generate/:org_slug

Both POST and GET methods are supported. POST is recommended for requests with complex parameters.

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
template_id	string	Yes	-	Unique identifier for the template for which content is being fetched.
user_id	string	No	-	Unique identifier for the end user (used for personalization and tracking).
tracking_id	string	No	-	Unique identifier for tracking this message through downstream events (opens, clicks, conversions).
fields	object	No	{}	Key-value pairs for LiquidJS template variable substitution.
attrs	object	No	{}	Key-value pairs for targeting/filtering (all values converted to lowercase).

Examples

Basic Request

Generate content for a welcome email:

cURL

curl -X POST https://worker.justwords.ai/api/generate/your-org \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "welcome-email",
    "user_id": "user_123"
  }'

JavaScript

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

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

Python

import requests

url = "https://worker.justwords.ai/api/generate/your-org"
headers = {
    "X-Api-Key": "your_api_key",
    "Content-Type": "application/json"
}
payload = {
    "template_id": "welcome-email",
    "user_id": "user_123"
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()
print(data["copy"])

Node.js

const https = require('https');

const data = JSON.stringify({
  template_id: 'welcome-email',
  user_id: 'user_123',
});

const options = {
  hostname: 'worker.justwords.ai',
  port: 443,
  path: '/api/generate/your-org',
  method: 'POST',
  headers: {
    'X-Api-Key': 'your_api_key',
    'Content-Type': 'application/json',
    'Content-Length': data.length,
  },
};

const req = https.request(options, (res) => {
  let body = '';
  res.on('data', (chunk) => (body += chunk));
  res.on('end', () => {
    const result = JSON.parse(body);
    console.log(result.copy);
  });
});

req.on('error', (error) => console.error(error));
req.write(data);
req.end();

With Personalization Fields

Pass user-specific data to personalize the content:

{
  "template_id": "welcome-email",
  "user_id": "user_123",
  "fields": {
    "user_name": "Alice",
    "account_type": "premium",
    "signup_date": "2024-01-15"
  }
}

These fields are used by your template’s LiquidJS variables (e.g., {{ user_name }} becomes “Alice”).

With Targeting Attributes

Filter which variants are eligible based on user attributes:

{
  "template_id": "welcome-email",
  "user_id": "user_123",
  "attrs": {
    "plan": "premium",
    "region": "us-east",
    "language": "en"
  }
}

Only variants matching these attributes will be considered for selection.

With Tracking ID

Link this generation to downstream events for performance measurement:

{
  "template_id": "welcome-email",
  "user_id": "user_123",
  "tracking_id": "msg_xyz789"
}

Use this tracking_id when sending open/click/conversion events via webhooks.

Response

Standard Response (200 OK)

{
  "copy": {
    "id": "variant_abc123",
    "vars": {
      "subject": "Welcome to our platform, Alice!",
      "body": "We're excited to have you join us.",
      "preheader": "Get started in minutes"
    }
  }
}

Response Fields

Field	Type	Description
copy.id	string	Unique identifier for the selected variant.
copy.vars	object	Key-value pairs of rendered template variables.

Empty Response

When no variants match the criteria:

{
  "copy": {},
  "message": "No candidates found"
}

This can happen if:

• All variants are filtered out by targeting rules.
• No variants are active for this template.
• Seasonality rules exclude all variants at this time.