Personyze Wiki Personyze Wiki docs
Open Personyze
App & API Campaigns

JSON API — Content Recommendations

Get content recommendations as raw JSON and render them in your own layout — catalog, interaction reporting, algorithm modifiers, and the response shape.

Updated 2 days ago 3 min read
A
by Admin

Content recommendations delivered as raw JSON instead of a rendered widget, so you can render them in your own layout. Ideal for a custom-designed carousel, a single-page app, a native app, or a “you may also like” block that has to match your own design system exactly.

In the panel: New campaign › App / API › JSON API — Content Recs.

The steps

Six steps: Catalog, Interactions, Recommendation, Data in Response, Code and Performance.

1. Catalog

Your content catalog — articles, guides, videos. Each item needs an internal ID, a title and a URL, plus an image if your layout uses one. Categories and tags are worth filling in properly: they are what allows recommendations to follow a topic rather than just overall popularity.

2. Interactions

The engine learns from what people read, like, comment on and complete. Because you are rendering the JSON yourself, you must report these interactions yourself — Personyze cannot infer a read from a layout it did not draw.

Skipping this is the usual reason a JSON content recommendation returns the same generic list to everyone: it has no reading history to personalize against.

3. Recommendation

Choose the context — home page, article page, category page — and the algorithm. The modifiers available:

  • Time window — today, recently, the last few days, the last week, or all time.
  • Category scope — from all categories, or from the current article’s category.
  • Interest scope — from the visitor’s inferred interests.
  • Freshness and ordering — recent first, oldest first, recently added, or new since the visitor’s last visit.
  • Co-occurrence — viewed together within the current category.

Filters narrow the pool further — content type, tag, category, or any custom field on your feed.

See Recommendation algorithm types for the algorithms in detail.

4. Data in Response

Personyze generates a JSON array of objects, each containing the fields you select. You are defining your own response contract here, so choose exactly what your renderer needs.

For each field, pick the source field from your catalog and give it the key name you want in the output. A typical content selection:

[
  {
    "internal_id": "nw-a001",
    "title": "How to layer for winter hiking",
    "category": "Skills",
    "image_1": "https://example.test/img/layering.jpg",
    "url": "https://example.test/journal/how-to-layer-for-winter-hiking"
  },
  ...
]

5. Code

The wizard produces the snippet to embed. Two ways to consume it:

  • On a page — the snippet assigns the JSON array to a JavaScript variable you name, and your own code renders it.
  • Server-side or from an app — call /rest/tracker-v1 and read the JSON out of the matching action’s data field. See Implementing a custom recommendations app.

6. Performance

Results once live — bounded by what you report back, as above.

Note: there is no QA step

JSON API campaigns have no QA step, because there is no rendered content to preview. Validate by fetching the JSON and checking it yourself: the right number of items, the fields you selected present, and values populated rather than empty.

Related