> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reelevant.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Technical Integration

> API endpoints, request format, response structure, and code examples for consuming Reelevant JSON output

## 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}
```

| Parameter      | Type  | Description                                                                                                  |
| -------------- | ----- | ------------------------------------------------------------------------------------------------------------ |
| `workflowId`   | path  | The workflow ID (visible in the workflow editor URL or integration modal)                                    |
| `entrypointId` | path  | The entrypoint ID within the workflow                                                                        |
| `rlvt-u`       | query | User 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:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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

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

## Code examples

### JavaScript (fetch)

```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```tsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 declares a `type` that tells the Runner how to resolve its dependency:

| `type`   | Extra field       | Behaviour                                                 | Example use case                                        |
| -------- | ----------------- | --------------------------------------------------------- | ------------------------------------------------------- |
| `scalar` | —                 | Resolves to a single value, auto-selected per branch      | User's name, a single product recommendation            |
| `array`  | —                 | Resolves to an array of all values across datasource rows | List of recommended products, category names            |
| `fixed`  | `index` (0-based) | Resolves to the value at a fixed datasource position      | Always the 1st (`index: 0`) or 3rd (`index: 2`) product |

The UI exposes `fixed` positions as **Datasource item #1 … #20**; item #N maps to `index: N - 1`.

### 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.