Personalization API Quickstart: Ship a For You Feed in One API Call

A personalization API lets you rank an existing set of posts, products, or content for an individual user through a single request. Instead of building your own ranking service, your application retrieves eligible candidates, sends them to the API, and renders the personalized order it returns.

For founders and developers building social apps, creator platforms, or discovery products, that removes a significant part of the infrastructure required for a "For You" feed.

But one API call does not mean one line of code creates an entire recommendation system.

You still need candidate retrieval, user context, feed rendering, event tracking, and fallback behavior.

This quickstart walks through those boundaries, demonstrates Gortex's published API request structure, and explains how to progress from a working feed to a production-ready integration.

A personalization API provides an interface for delivering user-specific recommendations or ranking decisions.

Depending on the provider, it may generate candidates, rank supplied candidates, or manage both processes.

For a "For You" feed, the key question is:

Given this user and these eligible posts, which ones should appear first?

A ranking-focused personalization API answers that question without requiring your application to operate its own ranking infrastructure.

Typical inputs include user identity, surface context, candidate identifiers, and available item features.

The output is an ordered set of items that your existing frontend can display.

Some recommendation services handle retrieval and ranking together. Others, including Gortex, focus on deciding the order of candidates you already provide. Understanding the difference between a recommendation API and a recommendation engine helps developers choose the right integration without unnecessary infrastructure.

A personalized feed usually separates candidate retrieval from ranking.

Google's research paper, Deep Neural Networks for YouTube Recommendations, describes a two-stage architecture containing candidate generation and ranking.

The retrieval stage narrows a large video collection into hundreds of candidates. The ranking stage evaluates those candidates more precisely.

The same architectural separation appears in TensorFlow Recommenders' ranking documentation, where retrieval identifies promising items before more detailed ranking.

For a startup, a simpler implementation can follow this request path:

User → Candidate Retrieval → Personalization API → Ranked Feed

Candidate retrieval might use your existing database, followed creators, relevant topics, or recent posts.

The personalization API then determines the ordering.

Your frontend renders those results and records engagement events.

The distinction is critical: personalization improves how eligible content is ordered. It cannot reliably recover relevant content that retrieval never supplied.

You can begin without a dedicated machine learning team, but your application needs a few basic components.

1. A stable user identifier

Each user should have an application-level identifier that can be included in ranking requests.

2. Eligible candidate items

Retrieve a collection of posts that satisfy visibility, moderation, availability, and access rules.

3. Surface context

Identify where results will appear, such as home_feed or for_you.

4. An authenticated backend

Your server should call the API securely. Do not expose private API credentials in client-side JavaScript.

5. A feed renderer

Your application must resolve returned identifiers into content cards and render them in order.

For the Gortex-specific example below, you also need private-beta access and an API key.

Gortex's personalization API documents a single decision endpoint:

POST /v1/decide

The request supplies a recipient, context, and items. The response returns ranking decisions, optional sponsored placements, and tracing identifiers.

The following request demonstrates the published top-level structure:

curl https://api.gortex.ai/v1/decide \
  -H "Authorization: Bearer $GORTEX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": {
      "id": "u_8120"
    },
    "context": {
      "surface": "home_feed"
    },
    "items": []
  }'

The endpoint and top-level field names are documented. The empty items array is only a structural placeholder, not a useful production request. Replace it with actual candidate objects conforming to the current API schema.

The published documentation illustrates a response shaped like:

{
  "ranked": [],
  "sponsored": [],
  "decision_id": "d_example",
  "trace_id": "t_example"
}

This is an abbreviated response illustration, not an actual result from an executed request.

The ranked output provides ordering information. Your application uses that ordering to render the appropriate content.

The decision and trace identifiers support debugging and auditing.

The integration boundary is simple: your application supplies candidates; the API returns the decision.

Imagine a social application retrieving 200 eligible posts for a user.

The personalization service evaluates those candidates and returns an ordered sequence.

A conceptual result might be:

post_205 → post_101 → post_309

Your backend maps those identifiers to its existing content records.

The frontend displays the posts in the returned order.

The application then records impressions, clicks, saves, hides, and other relevant interactions.

Keeping retrieval and rendering separate from ranking makes it possible to replace ranking services, compare algorithms, and recover from failures without rewriting the entire feed.

This separation is also the foundation of a feed ranking API architecture, where ranking decisions move to a managed endpoint while candidate retrieval and application logic remain under your control.

A personalization API and an internal ranking service can support similar product experiences.

The difference is primarily infrastructure ownership.

A managed API reduces certain engineering responsibilities but introduces service dependency, integration work, and ongoing evaluation requirements.

Building internally provides more control, but every change becomes an operational responsibility.

Neither option guarantees superior recommendation quality without measurement.

Personalization depends on the signals available to the ranking system.

For a content feed, those signals may include user preferences, item freshness, creator affinity, topic relevance, and past interactions.

Not every signal carries equal meaning.

A completed video, a quick scroll, and an explicit hide action represent different kinds of feedback.

The right signals depend on the product's objective.

A creator platform may prioritize meaningful engagement. A marketplace may prioritize relevant transactions. A learning application may care more about completion.

Do not optimize clicks automatically when the actual objective is retention or user satisfaction.

Also distinguish available data from model capability.

Sending interaction features does not guarantee a provider uses them in a learned personalization model.

Confirm how each API processes signals before choosing it.

New users have limited behavioral history.

This creates the cold-start problem: the system must order content without reliable individual preferences.

A practical startup implementation should use fallback signals.

These might include onboarding interests, language, location when appropriate, freshness, editorial quality, and broadly relevant content.

For new creators or posts, metadata can provide initial relevance before meaningful interaction data accumulates.

Avoid using global popularity as the entire strategy.

Popularity-only feeds can concentrate exposure on established creators and make discovery difficult for new content.

Instead, combine reasonable defaults with controlled exploration.

As engagement data accumulates, evaluate whether your ranking provider can incorporate those signals into later decisions.

A feed ranking call sits inside a user-facing request path.

Its latency contributes to the time users wait for content.

Measure response-time percentiles rather than relying exclusively on averages.

For example, a hypothetical feed-serving budget could allocate:

These figures are planning assumptions, not measured performance.

Gortex provides sub-200ms p99 decision latency in private beta.

Production validation should use realistic candidate batches, concurrency, network regions, and feature payloads.

Also implement a timeout and fallback ranker.

When the API becomes unavailable, your application should still serve a reasonable feed using recency, cached ordering, or another deterministic strategy.

A personalized feed is only useful if its ordering improves the outcomes that matter to your product.

Track more than API success rates.

Useful metrics include feed load latency, item impressions, click-through rate, session engagement, content diversity, user retention, and negative feedback.

For a creator platform, monitor whether recommendation changes concentrate impressions among a small group of creators.

For a marketplace, measure downstream transactions alongside engagement.

Start with a baseline ranker and compare it with the API-driven ranking through randomized experiments.

One useful metric is engagement per thousand feed impressions:

Engagement Rate = Engagement Events / Feed Impressions × 1,000

However, engagement alone may hide quality problems.

Use retention, hides, reports, and other product-specific guardrails to understand the broader impact.

Some personalization APIs can resolve sponsored placements alongside organic ranking.

Others require a separate advertising system.

Gortex's documented decision contract supports organic ordering and sponsored-slot decisions within the same response.

This becomes relevant when a social platform plans to monetize its feed without introducing another independent placement engine.

Sponsored items must still satisfy eligibility and relevance constraints, and the frontend must disclose commercial placements clearly.

A ranking-and-placement API is not necessarily a complete ad server. Campaign management, advertiser billing, attribution, and auction functionality may remain outside its scope, making the distinction between a sponsored listings API and complete advertising infrastructure important when designing a monetization system.

A successful API response is the beginning of integration, not the end.

Use a staged rollout.

Stage 1: Validate the contract. Confirm authentication, candidate schemas, response identifiers, errors, and limits.

Stage 2: Run shadow requests. Compare API ordering with your existing ranking without changing the user experience.

Stage 3: Enable limited traffic. Test a randomized cohort and measure engagement, latency, and negative feedback.

Stage 4: Verify fallbacks. Simulate errors, slow responses, empty candidates, and invalid items.

Stage 5: Expand gradually. Increase traffic after quality and reliability meet predefined acceptance criteria.

Preserve a rollback path until the new ranking service demonstrates stable results.

Gortex provides a decisioning API for platforms that already have candidate retrieval and want per-user ranking without maintaining their own ranking decision service.

Its POST /v1/decide endpoint accepts recipient, surface, and candidate information.

The API returns a ranked order, sponsored placements where applicable, and decision identifiers.

Gortex currently documents calibrated linear ranking, deterministic sponsored-slot filling, and traceability.

A learned ranking model and real-time auction functionality are roadmap capabilities.

That matters because Gortex should not be represented as an already deployed deep-learning personalization engine.

Its immediate proposition is a unified decision layer for ranking and monetization, with a narrower operational boundary than a complete recommendation platform.

For applications with an existing retrieval system, Gortex's feed ranking API provides an approach to consolidating ranking decisions and sponsored placement into one endpoint, which teams can evaluate through private-beta access.

A personalization API can help founders and developers launch a "For You" feed without building an entire ranking service.

The essential architecture is straightforward:

Retrieve eligible candidates, request a personalized order, render the feed, and measure user outcomes.

The difficult work shifts toward choosing the right signals, enforcing product constraints, validating latency, and continuously evaluating recommendation quality.

One API call can simplify the ranking decision. Building a genuinely useful personalized feed still requires thoughtful product and engineering decisions.

Can I build a For You feed with one API call?

You can obtain personalized ranking decisions with one call when candidate retrieval already exists. You still need content storage, rendering, event tracking, and operational safeguards.

Do I need a machine learning team?

Not necessarily. Managed APIs and deterministic ranking approaches can support useful feed ordering without an internal ML team.

Is a personalization API the same as a recommendation engine?

No. The API defines access to functionality. A recommendation engine is the underlying system that produces recommendation decisions.

Can I use a personalization API with React or Next.js?

Yes. Call the API through a secure backend and send the ranked results to your frontend. Keep private credentials server-side.

What happens when the API fails?

The application should use a documented fallback, such as recency ranking or cached results, so users can continue browsing.