Skip to main content

​
Runner endpoint

Every published workflow exposes a runner URL. When the output node is a JSON Template, the runner returns application/json instead of HTML or an image. 
GET https://reelevant.run/{workflowId}/{entrypointId}?rlvt-u={userId}
ParameterTypeDescription
workflowIdpathThe workflow ID (visible in the workflow editor URL or integration modal)
entrypointIdpathThe entrypoint ID within the workflow
rlvt-uqueryUser identifier for personalisation. Can be an email, internal user ID, or the rlvt_tmpId anonymous cookie
The response is a JSON object whose shape matches the template schema defined in the platform.

​
Response format

The response body is the resolved template data directly — no wrapper envelope. Static fields are returned as-is and dependency fields are replaced with real values from datasources: 
{
  "headline": "Recommended for you",
  "productName": "Running Shoes Pro",
  "productPrice": 129.99
}

​
Content-Type header

The runner returns Content-Type: application/json; charset=utf-8 for JSON Template output nodes.

​
HTTP status codes

StatusMeaning
200Workflow executed successfully. Body contains the JSON payload.
204Workflow executed but no content was produced (e.g., all branches were empty).
404Workflow not found or not published.

​
Code examples

​
JavaScript (fetch)

const workflowId = 'your-workflow-id'
const userId = 'user@example.com'

const response = await fetch(
  `https://reelevant.run/${workflowId}/0?rlvt-u=${encodeURIComponent(userId)}`
)

if (response.ok) {
  const data = await response.json()
  // data.headline, data.productName, data.productPrice, etc.
  renderRecommendation(data)
}

​
React

function Recommendation({ workflowId, userId }: Props) {
  const [data, setData] = useState(null)

  useEffect(() => {
    fetch(`https://reelevant.run/${workflowId}/0?rlvt-u=${userId}`)
      .then(res => res.json())
      .then(setData)
  }, [workflowId, userId])

  if (!data) return <Skeleton />

  return (
    <div className="recommendation-card">
      <h3>{data.headline}</h3>
      <p>{data.productName} — ${data.productPrice}</p>
      <a href={data.productUrl}>View product</a>
    </div>
  )
}

​
Python

import requests

workflow_id = "your-workflow-id"
user_id = "user@example.com"

response = requests.get(
    f"https://reelevant.run/{workflow_id}/0",
    params={"rlvt-u": user_id}
)

if response.ok:
    data = response.json()
    print(data["headline"], data["productName"])

​
cURL

curl -s "https://reelevant.run/{workflowId}/0?rlvt-u=user@example.com"

​
JSON Templates

​
What is a JSON Template?

A JSON Template is a reusable schema definition created in the Reelevant platform. It describes:
  • Definition — the JSON structure where each field is either { "type": "static", "value": ... } (fixed) or { "type": "dependency", "variable": "..." } (resolved at runtime)
  • Variables — named slots that map to datasource values, matching the variable names in the definition
Each variable is declared as either scalar (a single value) or array (a list of values from a datasource). This tells the engine how to resolve dependencies:
Variable typeBehaviourExample use case
ScalarResolves to a single value from the first datasource rowUser’s name, a single product recommendation
ArrayResolves to an array of all values across datasource rowsList of recommended products, category names

​
Template management API

JSON Templates are managed via the /workflows/json-templates REST API: 
POST   /workflows/json-templates          # Create a template
GET    /workflows/json-templates          # List templates (supports ?workflowId= filter and pagination)
GET    /workflows/json-templates/{id}     # Get a template by ID
PUT    /workflows/json-templates/{id}     # Update a template
DELETE /workflows/json-templates/{id}     # Delete a template

​
Publish-time validation

When you publish a workflow that uses JSON Template output nodes, the platform validates:
  1. All JSON Template nodes in the workflow reference the same template ID — ensuring a consistent response shape across branches.
  2. The referenced template exists and belongs to your company.
If validation fails, the publish is rejected with a descriptive error.

​
Combining with other integration methods

The JSON API approach works alongside the Client-Side Script and Server-Side SDK:
  • Use the Server-Side SDK to call the runner from your backend and pass JSON data to your frontend via props or server state.
  • Use the Client-Side Script for event tracking (impressions, clicks) alongside your JSON-powered UI.
  • Call the runner directly from the browser with fetch() if your use case is purely client-side.

​
Identity and personalisation

The rlvt-u query parameter drives personalisation. The value you pass determines which user profile the engine uses to select branches and resolve datasource queries. For best results:
  • Pass a stable user identifier (email, internal ID) when the user is logged in.
  • Pass the rlvt_tmpId cookie value for anonymous visitors — this preserves continuity with client-side tracking.
  • The same identity system powers all Reelevant channels (email, web, push), so personalisation is consistent across touchpoints.